Data APIs - Linkrunner

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
- "Unauthorized access." - Missing or invalid API key
429 Too Many Requests
- Message: "Rate limit exceeded. Please try again later."
- Cause: You’ve exceeded the rate limit of 30 requests per second.

Rate Limit Details

Rate: 30 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. (Refer instructions below)

Obtaining Your API Key

You can find your API key on the Linkrunner settings page:

Go to https://dashboard.linkrunner.io/settings?s=data-apis
Locate your Server key on this page
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 paginated list of campaigns with optional filtering by status or specific link.

Request

GET /campaigns

Query Parameters

Parameter	Type	Required	Description
filter	string	No	Filter campaigns by status. Options: `ACTIVE`, `INACTIVE`, `ALL` (default: `ALL`)
channel	string	No	Filter campaigns by advertising channel/network. Options: `GOOGLE`, `META`, `TIKTOK`, `APPLE_SEARCH_ADS`, or any affiliate name (case-insensitive). For affiliates, use underscores for spaces (e.g., `AFFILIATE_EXAMPLE` for “affiliate example”)
domain	string	No	Filter campaigns by domain name (e.g., `app.example.com`). Only returns campaigns associated with the specified domain.
link	string	No	Filter campaigns by a specific link URL. The system will extract the campaign from the provided link.
page	number	No	The page number to retrieve. Must be a positive integer. (default: `1`)
limit	number	No	The number of campaigns to return per page. Must be between 1 and 1000. (default: `100`, max: `1000`)

Channel Filter Behavior

Value	Behavior
`GOOGLE`	Returns campaigns where `google = true`
`META`	Returns campaigns where `meta = true`
`TIKTOK`	Returns campaigns linked to a TikTok ad network
`APPLE_SEARCH_ADS`	Returns campaigns linked to Apple Search Ads ad network
`AFFILIATE_EXAMPLE`	Returns campaigns linked to an affiliate named “affiliate example”. Replace spaces with underscores.
(empty/invalid)	No channel filter applied (returns all channels)

Affiliate Channel Naming:

Affiliate names should use underscores instead of spaces
Example: If the affiliate is named “affiliate example”, use channel=AFFILIATE_EXAMPLE
Channel names are case-insensitive

Pagination

Pagination is automatically applied to all requests with the following defaults:

Default page: 1
Default limit: 100 campaigns per page
Maximum limit: 1000 campaigns per page

Example Requests

Basic Request (returns first 100 campaigns):

GET /campaigns

Filter Active Campaigns with Pagination:

GET /campaigns?filter=ACTIVE&page=2&limit=50

Get Campaign by Link:

GET /campaigns?link=https://yourdomain.com?c=XYZ123

All Campaigns with Custom Limit:

GET /campaigns?filter=ALL&limit=200

Filter by Channel (Google):

GET /campaigns?channel=GOOGLE

Filter by Channel (Meta):

GET /campaigns?channel=META

Filter by Channel (TikTok):

GET /campaigns?channel=TIKTOK

Combine Channel with Other Filters:

GET /campaigns?channel=google&filter=ACTIVE&page=1&limit=50

Response

Standard Response (no channel filter):

{
    "msg": "Successfully retrieved 10 campaigns (all campaigns). Showing page 1 of 4.",
    "status": 200,
    "data": {
        "total_campaigns": 10,
        "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",
                "meta_web_to_app": false,
                "active": true,
                "default_link": true,
                "attributed_users": 491,
                "link": "https://yourdomain.com?c=XYZ123",
                "shareable_link": "https://yourdomain.com/XYZ123",
                "domain": "yourdomain.com",
                "store_listings": [
                    {
                        "store_listing_id": "ios-store-v1",
                        "name": "iOS Main Listing",
                        "platform": "IOS"
                    },
                    {
                        "store_listing_id": "android-promo-v2",
                        "name": "Android Promo Listing",
                        "platform": "ANDROID"
                    }
                ]
            }
            // ... more campaigns
        ],
        "pagination": {
            "total": 35,
            "pages": 4,
            "page": 1,
            "limit": 10
        }
    }
}

Error Responses

Status Code	Error Message	Description
400	”Invalid request parameters.”	Invalid link, domain not found, or campaign not found
400	”Invalid domain ''. Domain not found for this project.”	Specified domain does not exist or doesn’t belong to your project
400	”Invalid channel ''. Channel not found.”	Specified channel/ad network does not exist
401	”Unauthorized access.”	Missing or invalid API key
422	”Invalid page number ''. Page must be a positive integer…”	Page parameter is not a positive integer
422	”Invalid limit ''. Limit must be between 1 and 1000…”	Limit parameter is not between 1 and 1000
422	”Limit exceeds maximum allowed value of 1000…”	Limit exceeds 1000

TypeScript Types

interface StoreListing {
    store_listing_id: string;
    name: string;
    platform: "IOS" | "ANDROID";
}

interface Campaign {
    display_id: string;
    name: string;
    created_at: string;
    update_at: string;
    google: boolean;
    meta: boolean;
    meta_campaign_id: string | null;
    meta_web_to_app: boolean;
    active: boolean;
    default_link: boolean;
    attributed_users: number;
    link: string;
    shareable_link: string;
    domain: string | null;
    store_listings: StoreListing[];
}

interface PaginationInfo {
    total: number;
    pages: number;
    page: number;
    limit: number;
}

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

2. Get Attributed Users

Retrieve a paginated list of users attributed to a specific campaign with optional time range filtering.

Request

GET /attributed-users

Query Parameters

Parameter	Type	Required	Description
display_id	string	Yes	The display ID of the campaign to retrieve attributed users for
start_timestamp	string	No	Start time in ISO 8601 format (e.g., “2025-06-23T10:29:26.074”)
end_timestamp	string	No	End time in ISO 8601 format (e.g., “2025-06-23T10:29:26.074”)
timezone	string	No	IANA timezone identifier. See IANA Time Zone Database (default: `UTC`)
page	number	No	The page number to retrieve. Must be a positive integer. (default: `1`)
limit	number	No	The number of users to return per page. Must be between 1 and 1000. (default: `50`, max: `1000`)

Pagination

Pagination is automatically applied to all requests with the following defaults:

Default page: 1
Default limit: 50 users per page
Maximum limit: 1000 users per page

Time Format Details

ISO 8601 Format: Use YYYY-MM-DDThh:mm:ss.SSS format (e.g., 2025-06-23T10:29:26.074)
IANA Timezone: Standard timezone identifiers like America/New_York, Asia/Tokyo, Asia/Kolkata
Default Timezone: UTC is used when timezone parameter is not provided
Time Range: Both start and end timestamps are optional; you can filter by start time only, end time only, or both

Example Requests

Basic Request (returns first 50 users):

GET /attributed-users?display_id=XYZ123

With Time Range and Timezone:

GET /attributed-users?display_id=XYZ123&start_timestamp=2025-06-23T10:29:26.074&end_timestamp=2025-06-24T10:29:26.074&timezone=Asia/Kolkata

With Pagination:

GET /attributed-users?display_id=XYZ123&page=2&limit=100

With All Parameters:

GET /attributed-users?display_id=XYZ123&start_timestamp=2025-06-23T10:29:26.074&end_timestamp=2025-06-24T10:29:26.074&timezone=America/New_York&page=3&limit=200

Response

{
    "msg": "Successfully retrieved 123 attributed users for campaign XYZ123. Showing page 1 of 3.",
    "status": 200,
    "data": {
        "total_users": 50,
        "users": [
            {
                "attributed_at": "2024-09-23T08:13:34.417Z",
                "ad_channel": "META",
                "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",
                "publisher_platform": "instagram",
                "platform_position": null,
                "user_data": {
                    "id": "user123456789",
                    "name": "John Smith",
                    "email": "john.smith@example.com",
                    "phone": "+1234567890",
                    "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
        ],
        "pagination": {
            "total": 123,
            "pages": 3,
            "page": 1,
            "limit": 50
        }
    }
}

Error Responses

Status Code	Error Message	Description
400	”Invalid timezone format.”	Invalid IANA timezone identifier provided
400	”Invalid timestamp format.”	Invalid start or end timestamp format
401	”Authentication failed.”	Invalid or missing API key
404	”Resource not found.”	Campaign does not exist in the project
422	”Required parameter missing.”	Missing required display_id parameter
422	”Invalid page number ''. Page must be a positive integer…”	Page parameter is not a positive integer
422	”Invalid limit ''. Limit must be between 1 and 1000…”	Limit parameter is not between 1 and 1000
422	”Limit exceeds maximum allowed value of 1000…”	Limit exceeds 1000

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 | null;
    name: string | null;
    email: string | null;
    phone: string | null;
    device_data: DeviceData;
    // Additional user data fields may be included
    [key: string]: any;
}

interface AttributedUser {
    attributed_at: string;
    ad_channel: "GOOGLE" | "META" | "TIKTOK" | null;
    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;
    publisher_platform: string | null;
    platform_position: string | null;
    user_data: UserData;
}

interface PaginationInfo {
    total: number;
    pages: number;
    page: number;
    limit: number;
}

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

Campaign Domain and Store Listings

Domain Field

Each campaign response now includes a domain field that indicates which domain is being used for the campaign links:

Type: string | null
Description: The domain name used to generate campaign links
Behavior: If the campaign has a specific domain assigned, it will be shown. Otherwise, it falls back to the project’s primary domain.
Example: "yourdomain.com" or "promo.example.com"

Store Listings Array

Campaigns can now include multiple store listings in the response. Each store listing represents a different App Store or Play Store configuration. Store Listing Object Structure:

Field	Type	Description
`store_listing_id`	string	Unique identifier for the store listing
`name`	string	Display name of the store listing
`platform`	”IOS” \| “ANDROID”	Platform this store listing is for (iOS or Android)

Managing Store Listings:

Create and manage store listings in your Dashboard Settings
Each store listing has a unique store_listing_id that you use when creating campaigns
Store listings allow you to configure different App Store/Play Store parameters per campaign

3. Get Attribution Result

Retrieve attribution data for a specific user or device. This endpoint returns campaign and ad network information for attributed installs.

Request

GET /get-attribution-result

Query Parameters

Parameter	Type	Required	Description
device_identifier	string	Conditional	The unique device ID to look up. For Android, this is the GAID (Google Advertising ID). For iOS, this is the IDFA (Identifier for Advertisers). Required if `user_id` is not provided.
user_id	string	Conditional	The user ID to look up. Required if `device_identifier` is not provided.

Note: At least one of device_identifier or user_id must be provided. If both are provided and they match different installs, the user_id based result will be returned as it’s more reliable.

Example Requests

Get Attribution by Device Identifier:

GET /get-attribution-result?device_identifier=550e8400-e29b-41d4-a716-446655440000

Get Attribution by User ID:

GET /get-attribution-result?user_id=user123456

Get Attribution with Both Identifiers:

GET /get-attribution-result?device_identifier=550e8400-e29b-41d4-a716-446655440000&user_id=user123456

Response

Success Response (200):

{
    "msg": "Attribution result retrieved successfully.",
    "status": 200,
    "data": {
        "campaign_name": "Summer Sale 2024",
        "display_id": "XYZ123",
        "ad_network_campaign_id": "120214682829390250",
        "deeplink": "https://app.domain.com/promo/summer",
        "domain_name": "app.domain.com",
        "ad_set_id": "138726384957162840",
        "ad_set_name": "Engagement Campaign",
        "ad_creative_id": "138726495084763210",
        "ad_creative_name": "Creative Variation 1",
        "keyword_id": "",
        "keyword_name": "",
        "ad_network": "META",
        "attribution_type": "INORGANIC"
    }
}

No Attribution Data (204): If no attribution data is found for the provided identifier, the API returns a 204 No Content status with an empty response body.

Response Properties

Property	Type	Description
`campaign_name`	string\|null	The name of the campaign that the user was attributed to
`display_id`	string\|null	The campaign’s display identifier
`ad_network_campaign_id`	string\|null	The ad-network campaign ID (resolves to the Google campaign ID, else Meta campaign ID, else generic ad-network campaign ID)
`deeplink`	string\|null	The deeplink URL associated with the campaign
`domain_name`	string\|null	The domain name used for the campaign
`ad_set_id`	string\|null	The ad set ID from the advertising platform (e.g., Meta Ad Set ID)
`ad_set_name`	string\|null	The ad set name from the advertising platform
`ad_creative_id`	string\|null	The ad creative ID from the advertising platform
`ad_creative_name`	string\|null	The ad creative name from the advertising platform
`keyword_id`	string\|null	The keyword ID (primarily for Apple Search Ads campaigns)
`keyword_name`	string\|null	The keyword name (primarily for Apple Search Ads campaigns)
`ad_network`	string\|null	The advertising network. Can be `GOOGLE`, `META`, `TIKTOK`, `APPLE_SEARCH_ADS`, or other network codes
`attribution_type`	”ORGANIC”\|“INORGANIC”

Error Responses

Status Code	Error Message	Description
400	”Either device_identifier or user_id is required.”	Neither device_identifier nor user_id was provided
401	”Unauthorized access.”	Missing or invalid API key
204	No Content	No attribution data found for the provided identifier

TypeScript Types

type AdNetwork = "GOOGLE" | "META" | "TIKTOK" | "APPLE_SEARCH_ADS" | string;
type AttributionType = "ORGANIC" | "INORGANIC";

interface AttributionResult {
    campaign_name: string | null;
    display_id: string | null;
    ad_network_campaign_id: string | null;
    deeplink: string | null;
    domain_name: string | null;
    ad_set_id: string | null;
    ad_set_name: string | null;
    ad_creative_id: string | null;
    ad_creative_name: string | null;
    keyword_id: string | null;
    keyword_name: string | null;
    ad_network: AdNetwork | null;
    attribution_type: AttributionType;
}

interface AttributionResultResponse {
    msg: string;
    status: number;
    data: AttributionResult;
}

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
The domain field shows which domain is being used for campaign link generation
The store_listings array contains store listing configurations associated with the campaign
Store listings can be created and managed in the Dashboard Settings
The get-attribution-result endpoint returns a 204 status code with no body when no attribution data is found

For any help please reach out to support@linkrunner.io

​Base URL

​Authentication

​Error Responses

​Rate Limit Details

​Authentication

​API Key Header

​Obtaining Your API Key

​Endpoints

​1. List Campaigns

​Request

​Query Parameters

​Channel Filter Behavior

​Pagination

​Example Requests

​Response

​Error Responses

​TypeScript Types

​2. Get Attributed Users

​Request

​Query Parameters

​Pagination

​Time Format Details

​Example Requests

​Response

​Error Responses

​TypeScript Types

​Campaign Domain and Store Listings

​Domain Field

​Store Listings Array

​3. Get Attribution Result

​Request

​Query Parameters

​Example Requests

​Response

​Response Properties

​Error Responses

​TypeScript Types

​Notes

Base URL

Authentication

Error Responses

Rate Limit Details

Authentication

API Key Header

Obtaining Your API Key

Endpoints

1. List Campaigns

Request

Query Parameters

Channel Filter Behavior

Pagination

Example Requests

Response

Error Responses

TypeScript Types

2. Get Attributed Users

Request

Query Parameters

Pagination

Time Format Details

Example Requests

Response

Error Responses

TypeScript Types

Campaign Domain and Store Listings

Domain Field

Store Listings Array

3. Get Attribution Result

Request

Query Parameters

Example Requests

Response

Response Properties

Error Responses

TypeScript Types

Notes