Get one visitor’s attribution

import { createSiteClient } from '@fetchski/attract-cms-sdk';

const site = createSiteClient();
const getVisitorAttribution = await site.visitorAttribution().getVisitorAttribution({ visitorId: '0b8e6a4c-8d2f-4b6e-9a1c-3f5d7e9b1a2c' });

{
  "attribution": {
    "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"
  }
}

import { createSiteClient } from '@fetchski/attract-cms-sdk';

const site = createSiteClient();
const getVisitorAttribution = await site.visitorAttribution().getVisitorAttribution({ visitorId: '0b8e6a4c-8d2f-4b6e-9a1c-3f5d7e9b1a2c' });

{
  "attribution": {
    "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"
  }
}

In your app

A function makes the call on the client it is given, so your code passes the real one and a test passes a fake.

Add the function

src/attract/get-visitor-attribution.ts

import type { SiteClient } from '@fetchski/attract-cms-sdk';

export async function getVisitorAttribution(site: SiteClient, visitorId: string) {
  return site.visitorAttribution().getVisitorAttribution({ visitorId });
}

Call it

A script makes the client once and calls the function:

scripts/get-visitor-attribution.ts

import { createSiteClient } from '@fetchski/attract-cms-sdk';
import { getVisitorAttribution } from '../src/attract/get-visitor-attribution.ts';

const site = createSiteClient();
console.log(await getVisitorAttribution(site, '0b8e6a4c-8d2f-4b6e-9a1c-3f5d7e9b1a2c'));

Terminal

node --env-file=.env scripts/get-visitor-attribution.ts

A route handler, a job or a queue worker calls it the same way.

Required parameters

One object, e.g. getVisitorAttribution({ visitorId }); leave out the optional fields.

string

required

Required. The visitor ID. At most 128 characters.

Returns

A GetVisitorAttributionResponse. The record. Read its properties (getVisitorAttribution.attribution): each says whether the site always sends it.

VisitorAttribution

Always sent. A VisitorAttribution. One visitor’s attribution record. Kept for the site’s retention setting after the visitor’s last page view.

Show VisitorAttribution

string

Always sent.

AttributionTouch

Always sent. An AttributionTouch. One touch of a visitor’s journey on this site. Identifier values (clickIds, linker) appear only when the visitor allowed Marketing.

Show AttributionTouch

The visitor’s first visit on record; null when unknown.

Date

Sometimes sent: undefined when the site leaves it out. When the page view happened. Format: an ISO 8601 date and time.

string

Sometimes sent: undefined when the site leaves it out. The page’s path.

string

Sometimes sent: undefined when the site leaves it out. The full landing URL. Without Marketing consent its identifier parameters are removed. Format: an absolute URL.

string | null

Sometimes sent: undefined when the site leaves it out, and it can be null. Where the visitor came from; null for a direct visit.

readonly AdPlatforms[]

Sometimes sent: undefined when the site leaves it out. Platforms whose ad click ID the URL carried — kept for every visitor, consent or not. Each one of google, meta, tiktok, other.

Readonly<Record<string, string>>

Sometimes sent: undefined when the site leaves it out. UTM and campaign parameters (utm_*, gad_source, gad_campaignid, srsltid).

Readonly<Record<string, string>>

Sometimes sent: undefined when the site leaves it out. Ad click IDs (gclid, gbraid, wbraid, fbclid, ttclid). Marketing only.

Readonly<Record<string, string>>

Sometimes sent: undefined when the site leaves it out. Google’s cross-domain linker value (_gl). Marketing only.

boolean

Always sent. Whether the visitor allowed Marketing on their latest page view.

Date

Always sent. Format: an ISO 8601 date and time.

Date

Always sent. Format: an ISO 8601 date and time.

Date

Always sent. Format: an ISO 8601 date and time.

AttributionTouch

Sometimes sent: undefined when the site leaves it out. An AttributionTouch. One touch of a visitor’s journey on this site. Identifier values (clickIds, linker) appear only when the visitor allowed Marketing. Its fields are listed under the first AttributionTouch above.

Readonly<Record<string, string>>

Sometimes sent: undefined when the site leaves it out. Ad-platform browser IDs (_gcl_au — the cross-site key — _gcl_aw, _gcl_gb, _gcl_gs, _gcl_dc, _ga, _fbp, _fbc, _ttp). Marketing only.

Errors

Nothing to catch: the SDK retries what is safe, and throws the rest as the classes below; catch only what you want to react to (see Errors and testing).

401

The API key is missing, malformed, unknown, disabled, expired or archived (invalid), or a request that must be signed — by the route, or by the key’s own signing mode — has a missing, stale or wrong signature (an upload signs its SHA-256, declared in X-Fetchski-Content-SHA256, in the body’s place) (unauthorized).Retried first: No. Read: siteMessage, errorName, data.

403

The API key lacks the scope this route needs (the message names it), or the key is used from an address outside its allowlist.Retried first: No. Read: siteMessage, errorName, data.

404

Nothing with this identifier — or the caller may not use the Data API at all (anonymous visitors and non-admin sessions get 404 so the API is not advertised). A write while conversion tracking is switched off also answers 404.Retried first: No. Read: siteMessage, errorName, data.

429

The key used up its reads- or writes-per-minute limit (set per key; defaults 600 / 120). Still, after the client’s own waits and retries.Retried first: Yes: the client waits Retry-After (1 s when absent; over 60 s it gives up at once) and retries, up to retries times (2 by default). Read: retryAfter (seconds, or null), siteMessage.

5xx

The site failed (or something in front of it did). Its logs say why.Retried first: A 502, 503 or 504: yes, after 0.5 s then 1 s. A 500: no. Read: siteMessage, errorName, data.

no answer

No answer: DNS, a refused connection, TLS, or the timeout (15 s per attempt by default).Retried first: Yes, after 0.5 s then 1 s. Read: reason, neverConnected.

not sent

The client refused to send it (e.g. a path segment of ..); the site never saw it.Retried first: No. Read: reason (what to change).

any other

Any other status, or a success whose JSON doesn’t match this SDK version’s types (update the SDK).Retried first: No. Read: reason, status.

setup

sites.forSite('acme') named a slug your sites (createSiteClients()) don’t have.Retried first: No: nothing was sent. Read: message, slug.

setup

The client’s settings are wrong: no FETCHSKI_ATTRACT_URL (or baseUrl), or a malformed API key.Retried first: No: nothing was sent. Read: message (what to fix).

Behavior

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. The client waits and retries for you; you see RateLimited only if that runs out.
Retries: a read is safe to repeat: the client retries it on no answer, a 502/503/504 and a 429.
Timeout: 15 s per attempt by default; raise timeout (milliseconds) on the client for longer.

More examples

import { createSiteClient } from '@fetchski/attract-cms-sdk';

const site = createSiteClient();
const getVisitorAttribution = await site.visitorAttribution().findVisitorAttribution({ visitorId: '0b8e6a4c-8d2f-4b6e-9a1c-3f5d7e9b1a2c' }); // GetVisitorAttributionResponse | null: null when the site answers 404

Test it

It calls the function above with a fake client: the fake answers every call with a valid example, so nothing leaves your machine and no settings or key are needed. Run it with node --test.

tests/visitorAttribution-getVisitorAttribution.test.ts

import { test } from 'node:test';
import { fakeSite } from '@fetchski/attract-cms-sdk/testing';
import { getVisitorAttribution } from '../src/attract/get-visitor-attribution.ts';

test('visitorAttribution.getVisitorAttribution', async () => {
  const site = fakeSite();
  await getVisitorAttribution(site, '0b8e6a4c-8d2f-4b6e-9a1c-3f5d7e9b1a2c');
  site.assertCalled('visitorAttribution.getVisitorAttribution', (args) => args.visitorId === '0b8e6a4c-8d2f-4b6e-9a1c-3f5d7e9b1a2c');
});

Answer with your own values: fake visitorAttribution.getVisitorAttribution with factories.GetVisitorAttributionResponse({...}), the fields you give over a valid example (nested ones too).

tests/visitorAttribution-getVisitorAttribution-answer.test.ts

import assert from 'node:assert/strict';
import { test } from 'node:test';
import { factories, fakeSite } from '@fetchski/attract-cms-sdk/testing';

test('visitorAttribution.getVisitorAttribution answers your values', async () => {
  const site = fakeSite({
    'visitorAttribution.getVisitorAttribution': factories.GetVisitorAttributionResponse({ attribution: { visitorId: 'Your value' } })
  });
  const getVisitorAttribution = await site.visitorAttribution().getVisitorAttribution({ visitorId: '0b8e6a4c-8d2f-4b6e-9a1c-3f5d7e9b1a2c' });
  assert.equal(getVisitorAttribution.attribution.visitorId, 'Your value');
});

Find visitors by an identifier

site.visitorAttribution().findVisitorAttributions()

GET /visitor-attribution/{visitorId}

The endpoint this calls, in the API reference: the HTTP request and answer, and every rule the site checks.

import { createSiteClient } from '@fetchski/attract-cms-sdk';

const site = createSiteClient();
const getVisitorAttribution = await site.visitorAttribution().getVisitorAttribution({ visitorId: '0b8e6a4c-8d2f-4b6e-9a1c-3f5d7e9b1a2c' });

{
  "attribution": {
    "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"
  }
}

Get started

Using the SDK

Going further

Pages & Site

Content

Media

Forms

Ads & Conversions

Analytics

In your app

Behavior

More examples

Test it

Find visitors by an identifier

GET /visitor-attribution/{visitorId}

In your app

Behavior

More examples

Test it

Related

Find visitors by an identifier

GET /visitor-attribution/{visitorId}