Ads Metrics

Ad-click landings and conversions, aggregated

Totals for a time range (default: the last 30 days; at most 400 days per request), grouped by any of the groupBy dimensions (none = one total row). Two sections:

landings — page views whose URL carried an ad click ID, from the Request Log (every visitor counts; nothing identifying is used). Empty while the Request Log is switched off. Only day, platform (google, meta, tiktok, other), utmSource, utmCampaign and landingPath apply.
conversions — conversion events by when they happened. Always also grouped by currency. value sums restated values and leaves out retracted events. Grouped by platform (a destination such as google-ads), each row adds browser and server delivery outcomes — the delivery success rate.

Days are UTC. At most 5,000 rows per section.

Access: an API key with ads-metrics:read — or its group master ads:all, or admin:all — or a signed-in user holding the analytics:view permission. Anonymous callers get 404.

Rate limit: the key’s own reads-per-minute limit, set when the key is created (default 600); over it, 429 with Retry-After.

GET

ads-metrics

cURL

curl --request GET \
  --url https://{host}/api/v1/ads-metrics \
  --header 'Authorization: <api-key>'

{
  "from": "2026-09-01T00:00:00.000Z",
  "to": "2026-09-22T00:00:00.000Z",
  "groupBy": [
    "day",
    "platform"
  ],
  "landings": {
    "groupBy": [
      "day",
      "platform"
    ],
    "rows": [
      {
        "key": {
          "day": "2026-09-20",
          "platform": "google"
        },
        "landings": 41
      }
    ]
  },
  "conversions": {
    "groupBy": [
      "day",
      "platform"
    ],
    "rows": [
      {
        "key": {
          "currency": "USD",
          "day": "2026-09-20",
          "platform": "google-ads"
        },
        "conversions": 3,
        "retracted": 0,
        "value": 6400,
        "browserSent": 2,
        "serverSent": 3,
        "serverPending": 0,
        "serverFailed": 0,
        "serverSkipped": 0
      }
    ]
  }
}

{
  "name": "invalid",
  "message": "The query is not valid.",
  "data": {
    "errors": [
      {
        "name": "invalid",
        "code": 400,
        "path": "limit",
        "message": "A whole number from 1 to 500.",
        "data": {}
      }
    ]
  }
}

{
  "name": "unauthorized",
  "message": "X-Fetchski-Signature does not match this request.",
  "data": {}
}

{
  "name": "forbidden",
  "message": "This API key lacks the required scope: conversions:read.",
  "data": {}
}

{
  "name": "notfound",
  "message": "No event with this ID.",
  "data": {}
}

{
  "name": "tooManyRequests",
  "message": "This API key’s rate limit is used up for this minute.",
  "data": {
    "retryAfter": 12
  }
}

Authorizations

Authorization

string

header

required

Paste your API key as the CMS showed it: fsk_<site>_<key id>_<secret> (issued under API Keys). ApiKey in front of it works too. Leave it empty to read as the public.

Scopes

ads-metrics:read

Query Parameters

from

string<date-time>

Start (inclusive), ISO 8601 date or time. Default: 30 days before to.

string<date-time>

End (exclusive), ISO 8601 date or time. Default: now.

groupBy

enum<string>[]

Comma-separated dimensions, or the parameter repeated.

Available options:

day,

conversion,

platform,

utmSource,

utmCampaign,

landingPath

Response

The aggregates.

from

string<date-time>

required

The window’s start (inclusive).

string<date-time>

required

The window’s end (exclusive).

groupBy

enum<string>[]

required

The dimensions asked for.

Available options:

day,

conversion,

platform,

utmSource,

utmCampaign,

landingPath

landings

object

required

Page views whose URL carried an ad click ID (from the Request Log — empty while it is switched off). Grouped only by day, platform (google, meta, …), utmSource, utmCampaign and landingPath.

Show child attributes

conversions

object

required

Conversion events. value sums restated values and leaves out retracted events. Grouped by platform (a destination such as google-ads), each row adds delivery outcomes.

Show child attributes

cURL

curl --request GET \
  --url https://{host}/api/v1/ads-metrics \
  --header 'Authorization: <api-key>'

{
  "from": "2026-09-01T00:00:00.000Z",
  "to": "2026-09-22T00:00:00.000Z",
  "groupBy": [
    "day",
    "platform"
  ],
  "landings": {
    "groupBy": [
      "day",
      "platform"
    ],
    "rows": [
      {
        "key": {
          "day": "2026-09-20",
          "platform": "google"
        },
        "landings": 41
      }
    ]
  },
  "conversions": {
    "groupBy": [
      "day",
      "platform"
    ],
    "rows": [
      {
        "key": {
          "currency": "USD",
          "day": "2026-09-20",
          "platform": "google-ads"
        },
        "conversions": 3,
        "retracted": 0,
        "value": 6400,
        "browserSent": 2,
        "serverSent": 3,
        "serverPending": 0,
        "serverFailed": 0,
        "serverSkipped": 0
      }
    ]
  }
}

{
  "name": "invalid",
  "message": "The query is not valid.",
  "data": {
    "errors": [
      {
        "name": "invalid",
        "code": 400,
        "path": "limit",
        "message": "A whole number from 1 to 500.",
        "data": {}
      }
    ]
  }
}

{
  "name": "unauthorized",
  "message": "X-Fetchski-Signature does not match this request.",
  "data": {}
}

{
  "name": "forbidden",
  "message": "This API key lacks the required scope: conversions:read.",
  "data": {}
}

{
  "name": "notfound",
  "message": "No event with this ID.",
  "data": {}
}

{
  "name": "tooManyRequests",
  "message": "This API key’s rate limit is used up for this minute.",
  "data": {
    "retryAfter": 12
  }
}

Get started

How the API works

Pages & Site

Content

Media

Forms

Ads & Conversions

Analytics

Signing in (people)

Ad-click landings and conversions, aggregated

Authorizations

Scopes

Query Parameters

Response