Visitor Attribution

Find visitors by an identifier

Send exactly one lookup parameter. Returns every matching record, most recently seen first (at most 20) — a _gcl_au can in rare cases belong to several visitor IDs (for example when one of the two cookies was cleared and the other was not).

token opens an fk_at attribution token — the value this site adds to links to its Linked domains (a booking site) — and returns nothing once it has expired (90 days) or if it was forged. Click IDs match the first or last touch. emailSha256 / phoneSha256 find the visitors whose conversion events carried that hash (see UserDataHashes for the normalization).

Access: an API key with attribution:read — or its group master ads:all, or admin:all — or a signed-in user holding the attribution: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

visitor-attribution

cURL

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

{
  "matchedBy": "gclAu",
  "attributions": [
    {
      "visitorId": "0b8e6a4c-8d2f-4b6e-9a1c-3f5d7e9b1a2c",
      "firstTouch": {
        "at": "2026-09-20T09:12:00.000Z",
        "path": "/",
        "landingUrl": "https://example.com/?gclid=Cj0KCQjw&utm_source=google",
        "referrerOrigin": "https://www.google.com",
        "adPlatforms": [
          "google"
        ],
        "campaign": {
          "utm_source": "google",
          "utm_campaign": "spring-sale"
        },
        "clickIds": {
          "gclid": "Cj0KCQjw"
        }
      },
      "browserIds": {
        "_gcl_au": "1.1.1234567890.1790000000"
      },
      "marketing": true,
      "firstSeenAt": "2026-09-20T09:12:00.000Z",
      "lastSeenAt": "2026-09-21T15:04:05.000Z",
      "expiresAt": "2027-03-20T15:04:05.000Z"
    }
  ]
}

{
  "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

attribution:read

Query Parameters

token

string

An fk_at attribution token.

Maximum string length: 512

gclAu

string

The _gcl_au cookie value (Google’s cross-site browser ID).

Maximum string length: 512

fbp

string

The _fbp cookie value.

Maximum string length: 512

fbc

string

The _fbc cookie value.

Maximum string length: 512

ttp

string

The _ttp cookie value.

Maximum string length: 512

gclid

string

A Google click ID.

Maximum string length: 512

gbraid

string

A Google iOS app-campaign click ID.

Maximum string length: 512

wbraid

string

A Google iOS web-campaign click ID.

Maximum string length: 512

fbclid

string

A Meta click ID.

Maximum string length: 512

ttclid

string

A TikTok click ID.

Maximum string length: 512

emailSha256

string

SHA-256 of the trimmed, lower-cased email.

Pattern: ^[0-9a-f]{64}$

phoneSha256

string

SHA-256 of the E.164 phone number with its "+".

Pattern: ^[0-9a-f]{64}$

Response

The matching records (possibly none).

matchedBy

string

required

The lookup parameter used.

attributions

object[]

required

Maximum array length: 20

Show child attributes

cURL

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

{
  "matchedBy": "gclAu",
  "attributions": [
    {
      "visitorId": "0b8e6a4c-8d2f-4b6e-9a1c-3f5d7e9b1a2c",
      "firstTouch": {
        "at": "2026-09-20T09:12:00.000Z",
        "path": "/",
        "landingUrl": "https://example.com/?gclid=Cj0KCQjw&utm_source=google",
        "referrerOrigin": "https://www.google.com",
        "adPlatforms": [
          "google"
        ],
        "campaign": {
          "utm_source": "google",
          "utm_campaign": "spring-sale"
        },
        "clickIds": {
          "gclid": "Cj0KCQjw"
        }
      },
      "browserIds": {
        "_gcl_au": "1.1.1234567890.1790000000"
      },
      "marketing": true,
      "firstSeenAt": "2026-09-20T09:12:00.000Z",
      "lastSeenAt": "2026-09-21T15:04:05.000Z",
      "expiresAt": "2027-03-20T15:04:05.000Z"
    }
  ]
}

{
  "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)

Find visitors by an identifier

Authorizations

Scopes

Query Parameters

Response