Events Capture API

Using an AI coding agent? Let it instrument your events and revenue correctly (taxonomy, dedupe, refunds, and these server-side APIs):

npx @linkrunner/skills add events

See Linkrunner Agent Skills.

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.

Events are stored for all users, including organic ones. Events from users with no matching click are stored without campaign attribution. Each request must identify the user with user_id or install_instance_id. You can verify your events are being captured on the Events page. For capturing revenue, it is recommended to use the capture-payment API instead of capture-event.

Use Test Custom Events and Payments to decide whether an action belongs in this API or the Revenue Tracking API.

Base URL

https://api.linkrunner.io/api/v1

Authentication

Generate your server key from https://dashboard.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",
  "event_id": "evt_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 unless `install_instance_id` is sent. User identifier to associate with the event
install_instance_id	string	Required unless `user_id` is sent. Linkrunner’s ID for the install
event_id	string	Optional. Your own unique identifier for the event, useful for deduplication and correlating with your backend

Responses

200 Event captured successfully
400 Missing required parameters, or neither user_id nor install_instance_id was sent
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

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 support@linkrunner.io

Meta Ecommerce Events

If you are tracking Ecommerce events (like add_to_cart or view_content) to sync with Meta Catalog Sales, you must first map your custom event with the standard commerce event in the Linkrunner Dashboard before sending the event. Note: Any event you want to send for an add to cart action should be mapped with AddToCart for Commerce Event Manager. For example, map add_to_cart with AddToCart. Similarly, any event you want to send for viewing a product should be mapped with ViewContent. For example, map item_viewed with ViewContent or view_content with ViewContent. While you can include any custom attributes in the event_data object, Meta requires specific fields for ecommerce events in order to correctly attribute catalog sales and optimize campaigns.

Example Ecommerce Payload

Here is an example of the exact event_data structure you need to send for Meta Commerce Manager: For comprehensive details on each field requirement, refer to our Meta Commerce Manager documentation.

{
  "event_name": "add_to_cart",
  "event_data": {
    "content_ids": ["whshct4mwc"],
    "contents": [
      {
        "id": "whshct4mwc",
        "quantity": 2,
        "item_price": 1000
      }
    ],
    "content_type": "product",
    "currency": "INR",
    "value": 2000.0,
    "num_items": 2,
    "order_id": "order_id_1234"
  },
  "user_id": "user_12345"
}

To verify your events are being correctly received by Meta, please follow our Testing Ecommerce Events guide.

API Reference

Developer Tools

Base URL

Authentication

Capture Event

Request Body

Responses

Sample Response

Common Event Names

Best Practices

Example

Tracking a Purchase Event

Error Handling

Meta Ecommerce Events

Example Ecommerce Payload

​Base URL

​Authentication

​Capture Event

​Request Body

​Responses

​Sample Response

​Common Event Names

​Revenue Sharing with Ad Networks

​Best Practices

​Example

​Tracking a Purchase Event

​Error Handling

​Meta Ecommerce Events

​Example Ecommerce Payload

Base URL

Authentication

Capture Event

Request Body

Responses

Sample Response

Common Event Names

Revenue Sharing with Ad Networks

Best Practices

Example

Tracking a Purchase Event

Error Handling

Meta Ecommerce Events

Example Ecommerce Payload