Reporting API

Programmatic access to campaign analytics: clicks, installs, signups, spend, revenue, ROAS, ad sets, ad creatives, and keywords.

The Reporting API returns the same campaign analytics shown on the Linkrunner dashboard.

Base URL

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

Authentication

Pass your project’s server key in the linkrunner-key header. This is the same key used by other /api/v1 endpoints. Find it under Settings → Data APIs:

linkrunner-key: YOUR_API_KEY

Postman collection

Download the Postman collection. Import it into Postman, set the linkrunner_key collection variable to your key, and run any request.

Rate limit and freshness

• 1 request per minute per API key (429 with Retry-After: 60 when exceeded).
• 30 req/sec per source IP (shared across all /api/v1 endpoints).
• Underlying analytics refresh on roughly the same cadence, so cache responses for at least 60 seconds.

Endpoint

GET https://api.linkrunner.io/api/v1/reporting/campaigns

Do not call the docs page URL (/api-reference/reporting-campaigns) as the API endpoint. The API path is /api/v1/reporting/campaigns.

Example request

cURL

curl 'https://api.linkrunner.io/api/v1/reporting/campaigns?from=2026-04-01&to=2026-04-30&network=meta&limit=20' \
  -H 'linkrunner-key: YOUR_API_KEY'

Google Apps Script

const response = UrlFetchApp.fetch(
    "https://api.linkrunner.io/api/v1/reporting/campaigns?from=2026-04-01&to=2026-04-30&limit=20",
    {
        method: "get",
        headers: {
            "linkrunner-key": "YOUR_API_KEY",
        },
    }
);

const data = JSON.parse(response.getContentText());

Response

{
    "msg": "Campaigns fetched successfully",
    "status": 200,
    "data": {
        "campaigns": [ /* see TypeScript types below */ ],
        "pagination": { "total": 142, "pages": 8, "page": 1, "limit": 20 },
        "display_currency": "USD",
        "view": "user_acquisition"
    }
}

pagination.total is the number of campaigns matching your filters, and pages is total / limit rounded up.

Numeric fields are returned as formatted strings ("3,201", "$12,540.50"). Strip the formatting before doing math: Number(value.replace(/[^0-9.-]/g, "")).

Query parameters

Parameter	Type	Default	Notes
from, to	string	(none)	YYYY-MM-DD, inclusive, in your project’s timezone. start_date / end_date are accepted aliases. Sets the metrics window; never filters the campaign list (see note below).
active	string	(all)	true or false.
network	string	(all)	meta, google, apple_search_ads, tiktok, snapchat, sandbox_ads, etc.
meta_account_id	number	(none)	Restrict to a single Meta network account.
platform	string	(both)	ios or android.
search	string	(none)	Matches name, display ID, domain, deeplink, or full tracking URL.
view	string	user_acquisition	user_acquisition (new users: installs, cost_per_install) or retargeting (re-engaged users: reinstalls, reengagements, cost_per_reinstall).
sort_field	string	installs	clicks, installs, signups, revenue, spend, created_at, uninstalls, conversion, suspicious_installs, roas.
sort_order	string	descending	ascending or descending.
page	number	1	1-indexed.
limit	number	10	Max 100. Larger values return 422.

from and to choose the window over which metrics (clicks, installs, revenue, spend) are computed. They do not filter which campaigns are returned: a campaign created after to still appears, with zeros for the window. This matches the dashboard campaign table, where the date picker changes the numbers, not the list. To fetch only campaigns created in a range, see Troubleshooting.

See Configurable columns below for events, payment_events, unique_user_events, cost_per_event, and active_users.

Configurable columns

By default the response includes:

• All custom events your project tracks (under custom_events), each as a total occurrence count.
• All payment events (under payment_events), each as a total count and total amount.
• active_users with a 7-day window.

These query params let you narrow or change that:

Parameter	Effect	Example
events	Whitelist custom_events to only these names. Smaller payload, faster query.	events=Purchase,AddToCart
payment_events	Whitelist payment_events to only these types.	payment_events=PURCHASE
unique_user_events	Count distinct users (unique_count) for these events instead of total occurrences. Works for both custom and payment events.	unique_user_events=Purchase
cost_per_event	Include cost_per_custom_events / cost_per_payment_events for these event names. Off by default.	cost_per_event=Purchase,PURCHASE
active_users	Override the active-users window (in days).	active_users=14

All five accept a comma-separated list. Unknown event names are silently dropped (they map to no rows in our analytics store).

Find your project’s event names under Dashboard → Settings → Events.

Example: revenue events with cost-per and 14-day active users

curl -G 'https://api.linkrunner.io/api/v1/reporting/campaigns' \
  -H 'linkrunner-key: YOUR_API_KEY' \
  --data-urlencode 'events=Purchase,AddToCart' \
  --data-urlencode 'unique_user_events=Purchase' \
  --data-urlencode 'cost_per_event=Purchase' \
  --data-urlencode 'active_users=14' \
  --data-urlencode 'from=2026-04-01' \
  --data-urlencode 'to=2026-04-30' \
  --data-urlencode 'limit=20'

Returns each campaign with:

• custom_events.Purchase containing a unique_count (distinct paying users) instead of count.
• custom_events.AddToCart with the standard total count.
• cost_per_custom_events.Purchase (spend ÷ Purchase count).
• active_users computed over a 14-day window.

Errors

Status	When
401	Missing or invalid linkrunner-key.
402	Billing account suspended. Body includes payment_link.
422	limit is non-numeric, less than 1, or greater than 100.
429	Rate limit exceeded.
500	Unexpected server error. Retry after a short backoff.

Troubleshooting

Campaigns created outside my from/to range are in the response

This is expected. from and to set the metrics window; they never remove campaigns from the list. To keep only campaigns created in a range, request sort_field=created_at&sort_order=descending, then drop rows client-side once created_at falls before from.

429 Too Many Requests on the second call

The limit is 1 request per minute per API key. Honor the Retry-After: 60 header and cache responses for at least 60 seconds. The underlying analytics refresh on roughly the same cadence, so polling faster returns the same data.

Numbers don't match the dashboard

Compare the same date range and the same view (user_acquisition vs retargeting). The API interprets from and to in your project’s timezone, exactly like the dashboard date picker. If you are doing math on the values, remember they are formatted strings (see the warning under Response).

TypeScript types

export interface ReportingCampaignsResponse {
    msg: string;
    status: number;
    data: {
        campaigns: Campaign[];
        pagination: { total: number; pages: number; page: number; limit: number };
        display_currency?: string;
        view?: "user_acquisition" | "retargeting";
    };
}

export interface Campaign {
    id: number;
    active: boolean;
    created_at: string;
    display_id: string;
    link: string;
    name: string;

    // Counts (formatted strings)
    clicks: string;
    installs: string;
    reinstalls?: string;
    reengagements?: string;
    "sign-ups": string;
    uninstalls?: string;
    suspicious_installs?: string;
    click_through_attribution?: string;
    view_through_attribution?: string;
    conversion: string;

    // Money (formatted strings, in display_currency)
    revenue: string;
    revenue_event_count?: string;
    spend: string;
    roas?: string;
    cost_per_install?: string;
    cost_per_reinstall?: string;
    cost_per_signup?: string;

    // Network flags
    meta: boolean;
    meta_web_to_app: boolean;
    google: boolean;
    google_web_to_app: boolean;
    tiktok?: boolean;
    snapchat?: boolean;
    linkedin?: boolean;
    ad_network_code?: string;

    // Platforms
    ios: boolean;
    android: boolean;

    // Misc
    activity_in_last_x_days: number;
    has_date_filter: boolean;
    domain?: { id: number; name: string } | null;
    custom_store_listing: string | null;
    active_users?: number | string;

    // Custom & payment events: map of event name → count/amount
    custom_events?: { [name: string]: { count: string; amount?: string; unique_count?: string } | string };
    payment_events?: { [type: string]: { count: string; total: string } };
    cost_per_custom_events?: { [name: string]: string };
    cost_per_payment_events?: { [type: string]: string };

    // Retention buckets
    retention: { d1: number | string; d7: number | string };
    classic_retention?: { d1?: number | string; d7?: number | string; d14?: number | string; d30?: number | string };
    daywise_revenue?: { d0?: number | string; d3?: number | string; d7?: number | string; d30?: number | string };

    // Connected ad-account (Meta / Google / Apple Search Ads)
    network_account?: {
        id: number;
        name: string;
        email: string;
        status: string;
        capi_configured: boolean;
        account_name?: string;
        external_customer_id?: string;
    } | null;

    // Hierarchy: campaign → adSets → adCreatives + keywords
    adSets?: AdSet[];
}

export interface AdSet {
    id: string;
    name: string;
    clicks: string;
    installs: string;
    "sign-ups": string;
    spend: string;
    revenue: string;
    revenue_event_count?: string;
    conversion: string;
    roas?: string;
    cost_per_install?: string;
    cost_per_signup?: string;
    suspicious_installs?: string;
    custom_events?: Campaign["custom_events"];
    payment_events?: Campaign["payment_events"];
    cost_per_custom_events?: { [name: string]: string };
    cost_per_payment_events?: { [type: string]: string };
    daywise_revenue?: Campaign["daywise_revenue"];
    ios: boolean;
    android: boolean;
    retention: { d1: number | string; d7: number | string };
    adCreatives?: AdCreative[];
    keywords?: Keyword[];
}

export interface AdCreative {
    id: string;
    name: string;
    type: string;
    deeplink: number;
    clicks: string;
    installs: string;
    "sign-ups": string;
    spend: string;
    revenue: string;
    revenue_event_count?: string;
    conversion: string;
    roas?: string;
    cost_per_install?: string;
    cost_per_signup?: string;
    custom_events?: Campaign["custom_events"];
    payment_events?: Campaign["payment_events"];
    cost_per_custom_events?: { [name: string]: string };
    cost_per_payment_events?: { [type: string]: string };
    retention: { d1: number | string; d7: number | string };
}

// Apple Search Ads keyword-level rows. Same shape as AdCreative metrics.
export interface Keyword {
    id: string;
    name: string;
    clicks: string;
    installs: string;
    "sign-ups": string;
    spend: string;
    revenue: string;
    revenue_event_count?: string;
    conversion: string;
    roas?: string;
    cost_per_install?: string;
    cost_per_signup?: string;
    suspicious_installs?: string;
    custom_events?: Campaign["custom_events"];
    payment_events?: Campaign["payment_events"];
    cost_per_custom_events?: { [name: string]: string };
    cost_per_payment_events?: { [type: string]: string };
    retention?: { d1: number | string; d7: number | string };
}

Need help? Contact [e-mail]