This documentation is for tracking custom events from your backend only! For tracking events from your app please go through the Flutter or React Native documentation.
Base URL
https://api.linkrunner.io/api/v1
Authentication
Generate your server key from https://www.linkrunner.io/settings?s=data-apis
In the request header add the below attribute:
linkrunner-key: YOUR-SERVER-KEY
Capture Event
Request Body
{
"event_name": "product_viewed",
"event_data": {
"product_id": "ABC123",
"category": "electronics",
"amount": 249.99,
"currency": "USD",
"is_featured": true
},
"user_id": "user_12345"
}
| Parameter | Type | Description |
|---|
| event_name | string | Required. Name of the event to track |
| event_data | object | Optional. Additional data associated with the event |
| user_id | string | Required. User identifier to associate with the event |
Responses
- 201 Event captured successfully
- 400 Missing required parameters
- 401 Invalid server key
Sample Response
Upon successful event capture, the API returns:
{
"msg": "Event capture request received!",
"status": 200,
"data": null
}
Common Event Names
Here are some common event names you might want to track:
| Event Name | Description |
|---|
purchase_initiated | User starts a purchase |
purchase_completed | User completes a purchase |
item_viewed | User views an item/product |
cart_added | User adds item to cart |
checkout_started | User starts checkout |
search_performed | User performs a search |
content_viewed | User views content |
level_completed | User completes a level (for games) |
achievement_unlocked | User unlocks an achievement |
user_referred | User refers someone |
Revenue Sharing with Ad Networks
To enable revenue sharing with ad networks like Google Ads and Meta, include an amount parameter as a number in your custom event data. This allows the ad networks to optimize campaigns based on the revenue value of conversions:
{
"event_name": "purchase_completed",
"event_data": {
"product_id": "ABC123",
"category": "electronics",
"amount": 149.99
},
"user_id": "user_12345"
}
For revenue sharing with ad networks to work properly, ensure the amount parameter is passed as a number, not as a
string.
Best Practices
- Consistent naming: Use consistent naming conventions for your events (snake_case is recommended)
- Structured data: Include structured data with each event to get more insights
- Meaningful events: Track events that provide valuable insights into user behavior
- Data efficiency: Don’t include sensitive or unnecessary data in event payloads
Example
Tracking a Purchase Event
// Using fetch API
fetch("https://api.linkrunner.io/api/v1/capture-event", {
method: "POST",
headers: {
"Content-Type": "application/json",
"linkrunner-key": "YOUR-SERVER-KEY",
},
body: JSON.stringify({
event_name: "purchase_completed",
event_data: {
order_id: "ORD-12345",
product_ids: ["P-001", "P-002"],
total_amount: 125.99,
currency: "USD",
payment_method: "credit_card",
},
user_id: "user_12345",
}),
})
.then((response) => response.json())
.then((data) => console.log(data))
.catch((error) => console.error("Error:", error));
Error Handling
The API will return appropriate HTTP status codes along with error messages when issues occur:
- 400 Bad Request: Check your request parameters
- 401 Unauthorized: Verify your server key
- 429 Too Many Requests: You’ve exceeded the rate limit, please try again later
- 500 Internal Server Error: Contact support if this persists
For any help please reach out to darshil@linkrunner.io 
