​
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

ParameterTypeDescription
filterstringFilter campaigns by status (ACTIVE/INACTIVE/ALL)

​
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

ParameterTypeDescription
display_idstringThe display ID of the campaign

​
Example Request

GET /attributed-users?display_id=XYZ123

​
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