​
Base URL

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

​
Authentication

All API requests require authentication. Include your server key in the request headers.

​
Error Responses

  • 401 Unauthorized
    • "Server key missing!"
    • "Server key invalid!"
  • 429 Too Many Requests
  • Message: "Rate limit exceeded. Please try again later."
  • Cause: You’ve exceeded the rate limit of 10 requests per second.

​
Rate Limit Details

  • Rate: 10 requests per second
  • Status code on limit exceeded: 429 (Too Many Requests)

​
Authentication

All API requests require authentication using an API key. You must include this key in the header of every request.

​
API Key Header

Include the following header in all API requests: 
linkrunner-key: YOUR_API_KEY
Replace YOUR_API_KEY with your actual API key.

​
Obtaining Your API Key

You can find your API key on the Linkrunner settings page:
  1. Go to https://www.linkrunner.io/settings?s=data-apis
  2. Locate your Server key on this page
  3. Use this key in the linkrunner-key header for all API requests
Keep your API key confidential. Do not share it or expose it in client-side code. Always make API requests from a secure server-side environment.

​
Endpoints

​
1. List Campaigns

Retrieve a list of campaigns based on their status.

​
Request

GET /campaigns

​
Query Parameters

ParameterTypeRequiredDescription
filterstringNoFilter campaigns by status (ACTIVE/INACTIVE/ALL)
pagestringNoThe page number to retrieve (for pagination)
limitstringNoThe maximum number of results to return per page

​
Note

If ‘page’ and ‘limit’ are not provided, all campaigns will be returned in the response.

​
Example Request

GET /campaigns?filter=ALL

​
Response

{
    "msg": "Campaigns fetched successfully!",
    "status": 200,
    "data": {
        "total_campaigns": 35,
        "campaigns": [
            {
                "display_id": "XYZ123",
                "name": "Summer_Promo_2024",
                "created_at": "2024-09-30T09:37:06.989Z",
                "update_at": "2024-09-30T09:37:06.989Z",
                "google": false,
                "meta": true,
                "meta_campaign_id": "987654321098765432",
                "active": true,
                "default_link": true,
                "attributed_users": 491
            }
            // ... more campaigns
        ]
    }
}

​
TypeScript Types

interface Campaign {
    display_id: string;
    name: string;
    created_at: string;
    update_at: string;
    google: boolean;
    meta: boolean;
    meta_campaign_id: string | null;
    active: boolean;
    default_link: boolean;
    attributed_users: number;
}

interface CampaignsResponse {
    msg: string;
    status: number;
    data: {
        total_campaigns: number;
        campaigns: Campaign[];
    };
}

​
2. Get Attributed Users

Retrieve a list of users attributed to a specific campaign.

​
Request

GET /attributed-users

​
Query Parameters

ParameterTypeRequiredDescription
display_idstringYesThe display ID of the campaign
start_timestampstringNoStart time in ISO 8601 format (e.g., “2025-06-12T19:00:00”)
end_timestampstringNoEnd time in ISO 8601 format (e.g., “2025-06-12T19:00:00”)
timezonestringNoIANA timezone identifier. See IANA Time Zone Database
pagestringNoThe page number to retrieve (for pagination). Defaults to 1 if not specified.
limitstringNoThe maximum number of results to return per page. Defaults to 10 if not specified.

​
Note

If no timezone is provided, UTC (Coordinated Universal Time) will be used as the default timezone. If ‘page’ and ‘limit’ are not provided, all attributed users will be returned in the response.

​
Time Format Details

  1. ISO 8601 Time Format:
    • Format: YYYY-MM-DDThh:mm:ss
  2. IANA Timezone:
    • Use standard IANA timezone identifiers (e.g., “America/New_York”, “Asia/Tokyo”)
    • IANA Identifer for Indian Time Zone: “Asia/Kolkata”
    • Full list available at IANA Time Zone Database
    • Default: “UTC” (when timezone parameter is not provided)

​
Example Requests

  1. Basic Request (uses UTC by default):
GET /attributed-users?display_id=XYZ123
  1. With Time Range:
GET /attributed-users?display_id=XYZ123&start_timestamp=2025-06-12T19:00:00&end_timestamp=2025-06-13T19:00:00&timezone=Asia/Kolkata

​
Response

{
    "msg": "Attributed users fetched successfully!",
    "status": 200,
    "data": {
        "total_users": 23,
        "users": [
            {
                "attributed_at": "2024-09-23T08:13:34.417Z",
                "campaign_display_id": "XYZ123",
                "campaign_name": "Summer_Promo_2024",
                "link": null,
                "installed_at": "2024-08-12T20:59:03.000Z",
                "store_click_at": "2024-08-12T20:58:25.000Z",
                "meta_ad_id": "138726495012847390",
                "ad_creative_id": "138726495084763210",
                "ad_creative_name": "Variation_8",
                "ad_set_id": "138726384957162840",
                "ad_set_name": "Engagement",
                "is_instagram": true,
                "publisher_platform": "instagram",
                "platform_position": null,
                "user_data": {
                    "id": "user123456789",
                    "name": "John Smith",
                    "email": "john.smith@example.com",
                    "phone": "+1234567890",
                    "broker": null,
                    "deviceOs": "android",
                    "device_data": {
                        "brand": "Samsung",
                        "base_os": "",
                        "version": "0.7.6",
                        "build_id": "XYZ123.456",
                        "api_level": 33,
                        "bundle_id": "com.example.app",
                        "device_id": "DEVICE123456",
                        "android_id": "ANDROID987654",
                        "device_name": "Galaxy S21",
                        "device_type": "user",
                        "build_number": "2219",
                        "connectivity": "Wi-Fi",
                        "manufacturer": "Samsung",
                        "application_name": "ExampleApp"
                    }
                }
            }
            // ... more users
        ]
    }
}

​
TypeScript Types

interface DeviceData {
    brand: string;
    base_os: string;
    version: string;
    build_id: string;
    api_level: number;
    bundle_id: string;
    device_id: string;
    android_id: string;
    device_name: string;
    device_type: string;
    build_number: string;
    connectivity: string;
    manufacturer: string;
    application_name: string;
}

interface UserData {
    id: string;
    name: string | null;
    email: string | null;
    phone: string;
    broker: string | null;
    deviceOs: string;
    device_data: DeviceData;
}

interface AttributedUser {
    attributed_at: string;
    campaign_display_id: string;
    campaign_name: string;
    link: string | null;
    installed_at: string | null;
    store_click_at: string | null;
    meta_ad_id: string;
    ad_creative_id: string;
    ad_creative_name: string;
    ad_set_id: string;
    ad_set_name: string;
    is_instagram: boolean;
    publisher_platform: "instagram";
    platform_position: string;
    user_data: UserData;
}

interface AttributedUsersResponse {
    msg: string;
    status: number;
    data: {
        total_users: number;
        users: AttributedUser[];
    };
}

​
Notes

  • All timestamps are in ISO 8601 format.
  • The device_data object contains detailed information about the user’s device.
  • The active field in the campaign data indicates whether the campaign is currently active.
  • The attributed_users field in the campaign data shows the number of users attributed to that campaign.
  • User data provided in this documentation is randomized for privacy reasons. Actual API responses will contain real user data.
  • The TypeScript types provided are based on the example responses
For any help please reach out to darshil@linkrunner.io Want to track revenue using Linkrunner APIs? Checkout the documentation here

​
Linkrunner.io