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

POST: /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"
}
ParameterTypeDescription
event_namestringRequired. Name of the event to track
event_dataobjectOptional. Additional data associated with the event
user_idstringRequired. User identifier to associate with the event

​
Responses

  1. 201 Event captured successfully
  2. 400 Missing required parameters
  3. 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 NameDescription
purchase_initiatedUser starts a purchase
purchase_completedUser completes a purchase
item_viewedUser views an item/product
cart_addedUser adds item to cart
checkout_startedUser starts checkout
search_performedUser performs a search
content_viewedUser views content
level_completedUser completes a level (for games)
achievement_unlockedUser unlocks an achievement
user_referredUser 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

  1. Consistent naming: Use consistent naming conventions for your events (snake_case is recommended)
  2. Structured data: Include structured data with each event to get more insights
  3. Meaningful events: Track events that provide valuable insights into user behavior
  4. 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