Documentation

SDK setup, payloads, endpoints, and user data flow.

A-TRACK documentation for browser, SSR, backend, and analytics ingestion workflows. Start with init, attach attributes, track events, and query sessions back through the API.

On This Page

Overview

A-TRACK helps you create a session identity, ingest client and server context, attach attributes, track events, enrich the session with attribution and device data, and read the final structured profile back through API endpoints.

Public Key Auth

Send the SDK public key in the x-a-track-key header. Backend project routing and DB selection are resolved from that key.

UUID Flow

If no UUID is passed during init, the SDK can generate one, persist it locally, and reuse it for all future events and attribute updates.

Quick Start

  1. Initialize the SDK with your public key and optional known UUID.
  2. Send optional user and client context during init.
  3. Call setAttributes any time you want to attach or overwrite profile properties.
  4. Call track with an event name, event attributes, and optionally a known UUID override.
  5. Read back the enriched session through session/show or query events with event/show.

Official SDKs

Use the official A-TRACK SDK for your stack, or call the raw HTTP API directly if you want full control.

View GitHub Organization
SDK Use Case Repository
Frontend SDK
Browser, Vue, Nuxt, Next, Angular, plain JS		 frontend github.com/a-track-io/frontend-sdk
Node.js SDK
SSR, backend services, server-side event delivery		 nodejs github.com/a-track-io/nodejs-sdk
Python SDK
Backend apps, workers, data pipelines		 python github.com/a-track-io/python-sdk
Go SDK
High-performance backend services		 golang github.com/a-track-io/golang-sdk
Rust SDK
Low-level services and high-throughput ingestion		 rust github.com/a-track-io/rust-sdk
PHP SDK
PHP apps and Laravel-style backends		 php github.com/a-track-io/php-sdk
Swift SDK
Native Apple platform integrations		 swift github.com/a-track-io/swift-sdk
.NET SDK
C# applications and .NET services		 dotnet github.com/a-track-io/dotnet-sdk
Perl SDK
Legacy systems and Perl service integrations		 perl github.com/a-track-io/perl-sdk
Raw API
Direct HTTP integration without an SDK		 api Use the examples below on this page

Real-Life Examples

A common flow looks like this: a new user lands on your page from an ad click, the SDK initializes without a known UUID, your app reads the generated UUID, and later another part of your system tracks an event with that UUID explicitly.

1

Init without UUID, but with source URL and ad click context

Send the landing URL, UTM tags, and click IDs. A-TRACK creates the session UUID for you.

API
POST /init
x-a-track-key: your_public_key
content-type: application/json

{
  "context": {
    "url": {
      "href": "https://a-track.io/pricing?utm_source=google&utm_campaign=spring-launch&campaign_id=cmp_123&gclid=gclid_123&fbclid=fbclid_123",
      "raw": "/pricing?utm_source=google&utm_campaign=spring-launch&campaign_id=cmp_123&gclid=gclid_123&fbclid=fbclid_123",
      "path": "/pricing",
      "query": "?utm_source=google&utm_campaign=spring-launch&campaign_id=cmp_123&gclid=gclid_123&fbclid=fbclid_123",
      "source_url": "https://partner.example.com/blog/first-touch",
      "referer": "https://google.com/"
    },
    "client": {
      "ipAddress": "50.89.98.90",
      "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_2_1 like Mac OS X)",
      "locale": "en-US",
      "timezone": "America/New_York"
    }
  }
}
JavaScript SDK
const sdk = createATrackSdk({
  publicKey: "your_public_key"
});

await sdk.init({
  context: {
    url: {
      href: "https://a-track.io/pricing?utm_source=google&utm_campaign=spring-launch&campaign_id=cmp_123&gclid=gclid_123&fbclid=fbclid_123",
      raw: "/pricing?utm_source=google&utm_campaign=spring-launch&campaign_id=cmp_123&gclid=gclid_123&fbclid=fbclid_123",
      source_url: "https://partner.example.com/blog/first-touch",
      referer: document.referrer
    }
  }
});
Node.js SDK
const sdk = createATrackNodeSdk({
  publicKey: "your_public_key"
});

await sdk.init({
  context: {
    url: {
      href: "https://a-track.io" + req.url,
      raw: req.url,
      source_url: "https://partner.example.com/blog/first-touch",
      referer: req.headers.referer
    },
    client: {
      ipAddress: req.ip,
      userAgent: req.headers["user-agent"]
    }
  }
});
Python SDK
sdk = ATrackClient(public_key="your_public_key")

sdk.init({
    "context": {
        "url": {
            "href": "https://a-track.io/pricing?utm_source=google&utm_campaign=spring-launch&campaign_id=cmp_123&gclid=gclid_123&fbclid=fbclid_123",
            "raw": "/pricing?utm_source=google&utm_campaign=spring-launch&campaign_id=cmp_123&gclid=gclid_123&fbclid=fbclid_123",
            "source_url": "https://partner.example.com/blog/first-touch",
            "referer": "https://google.com/",
        }
    }
})
Go SDK
sdk := atrack.New(atrack.Options{
    PublicKey: "your_public_key",
})

_, err := sdk.Init(&atrack.InitPayload{
    Context: &atrack.Context{
        URL: &atrack.URLContext{
            Href:      "https://a-track.io/pricing?utm_source=google&utm_campaign=spring-launch&campaign_id=cmp_123&gclid=gclid_123&fbclid=fbclid_123",
            Raw:       "/pricing?utm_source=google&utm_campaign=spring-launch&campaign_id=cmp_123&gclid=gclid_123&fbclid=fbclid_123",
            SourceURL: "https://partner.example.com/blog/first-touch",
        },
    },
})
Rust SDK
let client = ATrackClient::new("your_public_key")?;

client.init(InitPayload {
    context: Some(Context {
        url: Some(UrlContext {
            href: Some("https://a-track.io/pricing?utm_source=google&utm_campaign=spring-launch&campaign_id=cmp_123&gclid=gclid_123&fbclid=fbclid_123".to_string()),
            raw: Some("/pricing?utm_source=google&utm_campaign=spring-launch&campaign_id=cmp_123&gclid=gclid_123&fbclid=fbclid_123".to_string()),
            source_url: Some("https://partner.example.com/blog/first-touch".to_string()),
            ..Default::default()
        }),
        ..Default::default()
    }),
    ..Default::default()
}).await?;
PHP SDK
$sdk = new ATrackClient([
    'publicKey' => 'your_public_key',
]);

$sdk->init([
    'context' => [
        'url' => [
            'href' => 'https://a-track.io/pricing?utm_source=google&utm_campaign=spring-launch&campaign_id=cmp_123&gclid=gclid_123&fbclid=fbclid_123',
            'raw' => '/pricing?utm_source=google&utm_campaign=spring-launch&campaign_id=cmp_123&gclid=gclid_123&fbclid=fbclid_123',
            'source_url' => 'https://partner.example.com/blog/first-touch',
        ],
    ],
]);
Swift SDK
let sdk = ATrackSDK(publicKey: "your_public_key")

try await sdk.init(.init(
    context: .init(
        url: .init(
            href: "https://a-track.io/pricing?utm_source=google&utm_campaign=spring-launch&campaign_id=cmp_123&gclid=gclid_123&fbclid=fbclid_123",
            raw: "/pricing?utm_source=google&utm_campaign=spring-launch&campaign_id=cmp_123&gclid=gclid_123&fbclid=fbclid_123",
            sourceUrl: "https://partner.example.com/blog/first-touch"
        )
    )
))
.NET SDK
var sdk = new ATrackSdk(new ATrackOptions
{
    PublicKey = "your_public_key"
});

await sdk.InitAsync(new InitPayload
{
    Context = new RequestContext
    {
        Url = new UrlContext
        {
            Href = "https://a-track.io/pricing?utm_source=google&utm_campaign=spring-launch&campaign_id=cmp_123&gclid=gclid_123&fbclid=fbclid_123",
            Raw = "/pricing?utm_source=google&utm_campaign=spring-launch&campaign_id=cmp_123&gclid=gclid_123&fbclid=fbclid_123",
            SourceUrl = "https://partner.example.com/blog/first-touch"
        }
    }
});
Perl SDK
my $sdk = ATrack::Client->new(
  public_key => 'your_public_key'
);

$sdk->init({
  context => {
    url => {
      href => 'https://a-track.io/pricing?utm_source=google&utm_campaign=spring-launch&campaign_id=cmp_123&gclid=gclid_123&fbclid=fbclid_123',
      raw => '/pricing?utm_source=google&utm_campaign=spring-launch&campaign_id=cmp_123&gclid=gclid_123&fbclid=fbclid_123',
      source_url => 'https://partner.example.com/blog/first-touch',
    },
  },
});
2

Read and store the generated UUID

Use the SDK response or getter to save the generated UUID in your app, CRM, or your own user profile.

API
{
  "success": true,
  "uuid": "b19412c6-6a91-4e18-890d-e2269a0d1249",
  "queued": false
}
JavaScript SDK
const initResult = await sdk.init({
  context: {
    url: {
      href: window.location.href,
      raw: window.location.pathname + window.location.search
    }
  }
});

const generatedUuid = initResult.uuid || sdk.getUserUuid();
localStorage.setItem("a_track_uuid", generatedUuid);
Node.js SDK
const initResult = await sdk.init({
  context: {
    url: {
      href: "https://a-track.io" + req.url,
      raw: req.url
    }
  }
});

const generatedUuid = initResult.uuid || sdk.getUserUuid();
Python SDK
init_result = sdk.init({
    "context": {
        "url": {
            "href": full_url,
            "raw": raw_url,
        }
    }
})

generated_uuid = init_result["uuid"]
Go SDK
result, err := sdk.Init(&atrack.InitPayload{
    Context: &atrack.Context{
        URL: &atrack.URLContext{
            Href: fullURL,
            Raw:  rawURL,
        },
    },
})

generatedUUID := result.UUID
Rust SDK
let init_result = client.init(InitPayload {
    context: Some(Context {
        url: Some(UrlContext {
            href: Some(full_url.to_string()),
            raw: Some(raw_url.to_string()),
            ..Default::default()
        }),
        ..Default::default()
    }),
    ..Default::default()
}).await?;

let generated_uuid = init_result.uuid;
PHP SDK
$initResult = $sdk->init([
    'context' => [
        'url' => [
            'href' => $fullUrl,
            'raw' => $rawUrl,
        ],
    ],
]);

$generatedUuid = $initResult['uuid'];
Swift SDK
let initResult = try await sdk.init(.init(
    context: .init(
        url: .init(
            href: fullUrl,
            raw: rawUrl
        )
    )
))

let generatedUuid = initResult.uuid ?? sdk.getUserUuid()
.NET SDK
var initResult = await sdk.InitAsync(new InitPayload
{
    Context = new RequestContext
    {
        Url = new UrlContext { Href = fullUrl, Raw = rawUrl }
    }
});

var generatedUuid = initResult.Uuid ?? sdk.GetUserUuid();
Perl SDK
my $init_result = $sdk->init({
  context => {
    url => {
      href => $full_url,
      raw  => $raw_url,
    },
  },
});

my $generated_uuid = $init_result->{uuid};
3

Track an event later with the saved UUID

Once you know the UUID, you can track events from another page, another process, or your backend explicitly against that same user session.

API
POST /event
x-a-track-key: your_public_key
content-type: application/json

{
  "uuid": "b19412c6-6a91-4e18-890d-e2269a0d1249",
  "event": "checkout_started",
  "attributes": {
    "cart_value": 129.99,
    "currency": "USD",
    "step": "payment"
  }
}
JavaScript SDK
const savedUuid = localStorage.getItem("a_track_uuid");

await sdk.track("checkout_started", {
  cart_value: 129.99,
  currency: "USD",
  step: "payment"
}, savedUuid);
Node.js SDK
await sdk.track({
  uuid: savedUuid,
  event: "checkout_started",
  attributes: {
    cart_value: 129.99,
    currency: "USD",
    step: "payment"
  }
});
Python SDK
sdk.track({
    "uuid": generated_uuid,
    "event": "checkout_started",
    "attributes": {
        "cart_value": 129.99,
        "currency": "USD",
        "step": "payment",
    },
})
Go SDK
err := sdk.Track(atrack.EventPayload{
    UUID:  generatedUUID,
    Event: "checkout_started",
    Attributes: atrack.Attributes{
        "cart_value": 129.99,
        "currency":   "USD",
        "step":       "payment",
    },
})
Rust SDK
client.track(EventPayload {
    uuid: Some(generated_uuid),
    event: "checkout_started".into(),
    attributes: Some(json!({
        "cart_value": 129.99,
        "currency": "USD",
        "step": "payment"
    })),
    ..Default::default()
}).await?;
PHP SDK
$sdk->track([
    'uuid' => $generatedUuid,
    'event' => 'checkout_started',
    'attributes' => [
        'cart_value' => 129.99,
        'currency' => 'USD',
        'step' => 'payment',
    ],
]);
Swift SDK
try await sdk.track(.init(
    uuid: generatedUuid,
    event: "checkout_started",
    attributes: [
        "cart_value": 129.99,
        "currency": "USD",
        "step": "payment"
    ]
))
.NET SDK
await sdk.TrackAsync(new EventPayload
{
    Uuid = generatedUuid,
    Event = "checkout_started",
    Attributes = new Dictionary<string, object>
    {
        ["cart_value"] = 129.99,
        ["currency"] = "USD",
        ["step"] = "payment"
    }
});
Perl SDK
$sdk->track({
  uuid => $generated_uuid,
  event => 'checkout_started',
  attributes => {
    cart_value => 129.99,
    currency => 'USD',
    step => 'payment',
  },
});
Code Examples

Switch every example at once

Pick API or any SDK language and we will update all code blocks below to match.

A-TRACK documentation overview

Init

POST /init creates or updates a session. If a UUID is present, A-TRACK continues the known identity. If UUID is missing, the backend creates one and returns it.

POST /init
POST /init
x-a-track-key: your_public_key
content-type: application/json

{
  "uuid": "optional-known-uuid",
  "context": {
    "url": {
      "href": "https://a-track.io/pricing?utm_source=google",
      "raw": "/pricing?utm_source=google",
      "path": "/pricing",
      "query": "?utm_source=google",
      "referer": "https://google.com/",
      "source_url": "https://partner.example.com/blog/post"
    },
    "client": {
      "ipAddress": "50.89.98.90",
      "userAgent": "Mozilla/5.0 ...",
      "locale": "en-US",
      "timezone": "America/New_York"
    }
  }
}
JavaScript SDK
const sdk = createATrackSdk({
  publicKey: "your_public_key"
});

const result = await sdk.init({
  context: {
    url: {
      href: window.location.href,
      raw: window.location.pathname + window.location.search,
      source_url: document.referrer
    }
  }
});

console.log(result.uuid);
Node.js SDK
const sdk = createATrackNodeSdk({
  publicKey: "your_public_key"
});

const result = await sdk.init({
  uuid: req.userUuid,
  context: {
    url: {
      href: "https://a-track.io" + req.url,
      raw: req.url,
      referer: req.headers.referer
    },
    client: {
      ipAddress: req.ip,
      userAgent: req.headers["user-agent"]
    }
  }
});
Python SDK
sdk = ATrackClient(public_key="your_public_key")

result = sdk.init({
    "uuid": known_uuid,
    "context": {
        "url": {
            "href": full_url,
            "raw": raw_url,
            "referer": referer,
        },
        "client": {
            "ipAddress": ip_address,
            "userAgent": user_agent,
        },
    },
})
Go SDK
sdk := atrack.New(atrack.Options{
    PublicKey: "your_public_key",
})

result, err := sdk.Init(&atrack.InitPayload{
    UUID: knownUUID,
    Context: &atrack.Context{
        URL: &atrack.URLContext{
            Href: fullURL,
            Raw:  rawURL,
        },
    },
})
Rust SDK
let client = ATrackClient::new("your_public_key")?;

let result = client.init(InitPayload {
    uuid: Some(known_uuid.to_string()),
    context: Some(Context {
        url: Some(UrlContext {
            href: Some(full_url.to_string()),
            raw: Some(raw_url.to_string()),
            ..Default::default()
        }),
        ..Default::default()
    }),
    ..Default::default()
}).await?;
PHP SDK
$sdk = new ATrackClient([
    'publicKey' => 'your_public_key',
]);

$result = $sdk->init([
    'uuid' => $knownUuid,
    'context' => [
        'url' => [
            'href' => $fullUrl,
            'raw' => $rawUrl,
        ],
    ],
]);
Swift SDK
let sdk = ATrackSDK(publicKey: "your_public_key")

let result = try await sdk.init(.init(
    uuid: knownUuid,
    context: .init(
        url: .init(
            href: fullUrl,
            raw: rawUrl
        )
    )
))
.NET SDK
var sdk = new ATrackSdk(new ATrackOptions
{
    PublicKey = "your_public_key"
});

var result = await sdk.InitAsync(new InitPayload
{
    Uuid = knownUuid,
    Context = new RequestContext
    {
        Url = new UrlContext { Href = fullUrl, Raw = rawUrl }
    }
});
Perl SDK
my $sdk = ATrack::Client->new(
  public_key => 'your_public_key'
);

my $result = $sdk->init({
  uuid => $known_uuid,
  context => {
    url => {
      href => $full_url,
      raw  => $raw_url,
    },
  },
});

Init Context Reference

Use these fields inside the context object of POST /init. Frontend SDKs can auto-collect many client-side values, while server-side SDKs usually pass values already known from the incoming request.

Attribute Path Description Auto-Captured Example
uuid Optional known session or user UUID. If omitted, A-TRACK generates one and returns it. No b19412c6-6a91-4e18-890d-e2269a0d1249
context.url.href Full absolute URL of the page or request entry point. Yes, frontend https://a-track.io/pricing?utm_source=google
context.url.raw Raw path and query string exactly as your app saw it. Yes, frontend /pricing?utm_source=google&gclid=gclid_123
context.url.path Path portion of the URL without domain or query string. Yes, frontend /pricing
context.url.query Raw query string. Used to extract UTM tags, click IDs, source, and other GET parameters. Yes, frontend ?utm_source=google&campaign_id=cmp_123
context.url.hash Optional fragment/hash from the current page URL. Yes, frontend #pricing
context.url.referer Document referer or upstream HTTP referer that sent the user to this page. Yes, frontend https://google.com/
context.url.source_url Original source page you want to preserve as first-touch context. Useful when the user passed through redirects, apps, or middle pages. No https://partner.example.com/blog/first-touch
context.client.ipAddress Client IP address used for geolocation, ASN, ISP, and proxy/VPN enrichment. No, usually server 50.89.98.90
context.client.userAgent Raw user agent used for browser, OS, device, and bot detection. Yes, frontend Mozilla/5.0 (iPhone; CPU iPhone OS 17_2_1 like Mac OS X)
context.client.locale Primary locale selected by the browser or known by your app. Yes, frontend en-US
context.client.language Primary browser language. Yes, frontend en-US
context.client.languages Ordered list of preferred browser languages. Yes, frontend ["en-US", "en"]
context.client.timezone IANA timezone name detected on the client. Yes, frontend America/New_York
context.client.timezoneOffsetMinutes Client timezone offset in minutes at the moment of init. Yes, frontend 240
context.client.platform Reported client platform string. Yes, frontend iPhone
context.client.screenWidth Physical screen width in pixels. Yes, frontend 1179
context.client.screenHeight Physical screen height in pixels. Yes, frontend 2556
context.client.viewportWidth Current viewport width in pixels. Yes, frontend 393
context.client.viewportHeight Current viewport height in pixels. Yes, frontend 852
context.client.pixelRatio Display pixel ratio. Yes, frontend 3
context.client.colorDepth Reported display color depth. Yes, frontend 24
context.client.cookiesEnabled Whether the browser reports cookies as enabled. Yes, frontend true
context.client.touchPoints Maximum simultaneous touch points reported by the device. Yes, frontend 5
context.client.deviceMemoryGb Approximate client device memory when available. Yes, frontend 8
context.client.hardwareConcurrency Logical CPU core count reported by the browser. Yes, frontend 6
context.client.connectionType Browser network connection type if exposed by the platform. Yes, frontend wifi
context.client.connectionEffectiveType Network quality hint such as 4g, 3g, or slow-2g. Yes, frontend 4g
context.client.connectionDownlinkMbps Estimated downlink speed in megabits per second. Yes, frontend 10.2
context.client.connectionRttMs Estimated round-trip time in milliseconds. Yes, frontend 50
context.user.attributes Optional initial user attributes you already know at init time. These become structured user/session data on the backend. No {"plan":"pro","signup_step":"landing"}
custom_data Optional custom JSON payload to store alongside the session for your own app logic. No {"landing_variant":"v2","widget_position":"hero"}
synchronous If true, the backend processes init immediately instead of queueing the job. No true

Set Attributes

POST /attributes accepts a UUID and a flat key-value attribute map. Existing keys are overwritten. Values may be scalars or JSON values.

POST /attributes
POST /attributes
x-a-track-key: your_public_key
content-type: application/json

{
  "uuid": "b19412c6-6a91-4e18-890d-e2269a0d1249",
  "attributes": {
    "plan": "pro",
    "signup_step": "landing",
    "custom_flags": {
      "beta": true
    }
  }
}
JavaScript SDK
await sdk.setAttributes({
  plan: "pro",
  signup_step: "landing",
  custom_flags: { beta: true }
});
Node.js SDK
await sdk.setAttributes({
  plan: "pro",
  signup_step: "landing"
}, false);
Python SDK
sdk.set_attributes({
    "plan": "pro",
    "signup_step": "landing",
    "custom_flags": {"beta": True},
})
Go SDK
_, err := sdk.SetAttributes(atrack.Attributes{
    "plan":        "pro",
    "signup_step": "landing",
}, false)
Rust SDK
client.set_attributes(json!({
    "plan": "pro",
    "signup_step": "landing"
}), false).await?;
PHP SDK
$sdk->setAttributes([
    'plan' => 'pro',
    'signup_step' => 'landing',
], false);
Swift SDK
try await sdk.setAttributes([
    "plan": "pro",
    "signup_step": "landing"
], replace: false)
.NET SDK
await sdk.SetAttributesAsync(new Dictionary<string, object>
{
    ["plan"] = "pro",
    ["signup_step"] = "landing"
}, replace: false);
Perl SDK
$sdk->set_attributes({
  plan => 'pro',
  signup_step => 'landing',
}, 0);

Track Event

POST /event records an event for a session UUID. The track method may also receive an optional UUID override if the event is emitted from another part of your stack where the session UUID is already known.

POST /event
POST /event
x-a-track-key: your_public_key
content-type: application/json

{
  "uuid": "b19412c6-6a91-4e18-890d-e2269a0d1249",
  "event": "checkout_started",
  "attributes": {
    "cart_value": 129.99,
    "currency": "USD"
  },
  "timestamp": "2026-04-12T02:10:00Z"
}
JavaScript SDK
await sdk.track("checkout_started", {
  cart_value: 129.99,
  currency: "USD"
});
Node.js SDK
await sdk.track({
  event: "checkout_started",
  uuid: knownUuid,
  attributes: {
    cart_value: 129.99,
    currency: "USD"
  }
});
Python SDK
sdk.track({
    "event": "checkout_started",
    "uuid": known_uuid,
    "attributes": {
        "cart_value": 129.99,
        "currency": "USD",
    },
})
Go SDK
err := sdk.Track(atrack.EventPayload{
    UUID:  knownUUID,
    Event: "checkout_started",
    Attributes: atrack.Attributes{
        "cart_value": 129.99,
        "currency":   "USD",
    },
})
Rust SDK
client.track(EventPayload {
    uuid: Some(known_uuid.to_string()),
    event: "checkout_started".into(),
    attributes: Some(json!({
        "cart_value": 129.99,
        "currency": "USD"
    })),
    ..Default::default()
}).await?;
PHP SDK
$sdk->track([
    'uuid' => $knownUuid,
    'event' => 'checkout_started',
    'attributes' => [
        'cart_value' => 129.99,
        'currency' => 'USD',
    ],
]);
Swift SDK
try await sdk.track(.init(
    uuid: knownUuid,
    event: "checkout_started",
    attributes: [
        "cart_value": 129.99,
        "currency": "USD"
    ]
))
.NET SDK
await sdk.TrackAsync(new EventPayload
{
    Uuid = knownUuid,
    Event = "checkout_started",
    Attributes = new Dictionary<string, object>
    {
        ["cart_value"] = 129.99,
        ["currency"] = "USD"
    }
});
Perl SDK
$sdk->track({
  uuid => $known_uuid,
  event => 'checkout_started',
  attributes => {
    cart_value => 129.99,
    currency => 'USD',
  },
});

Read APIs

POST /session/show

Accepts uuid and returns the full structured session: parsed URLs, UTM data, click IDs, IP enrichment, device info, attributes, and recent events.

POST /event/show

Accepts name, pagination input, and sort order. Returns all matching events with metadata for pagination and ordering.

Payload Examples

201 Created
{
  "success": true,
  "uuid": "b19412c6-6a91-4e18-890d-e2269a0d1249",
  "queued": false
}

200 OK
{
  "success": true,
  "uuid": "b19412c6-6a91-4e18-890d-e2269a0d1249",
  "queued": true
}

200 OK
{
  "success": true,
  "uuid": "b19412c6-6a91-4e18-890d-e2269a0d1249",
  "queued": false
}

200 OK
{
  "success": true,
  "data": {
    "session": {
      "id": 2,
      "uuid": "b19412c6-6a91-4e18-890d-e2269a0d1249",
      "url_data": {
        "raw": "/pricing?utm_source=google&utm_campaign=spring-launch&campaign_id=cmp_123&custom_param=test",
        "href": "https://a-track.io/pricing?utm_source=google&utm_campaign=spring-launch&campaign_id=cmp_123&custom_param=test",
        "path": "/pricing",
        "query": "?utm_source=google&utm_campaign=spring-launch&campaign_id=cmp_123&custom_param=test",
        "query_all": {
          "utm_source": "google",
          "utm_campaign": "spring-launch",
          "campaign_id": "cmp_123",
          "custom_param": "test"
        },
        "source_url": "https://partner.example.com/blog/first-touch"
      },
      "utm_data": {
        "utm_source": "google",
        "utm_campaign": "spring-launch",
        "campaign_id": "cmp_123"
      },
      "query_params": {
        "custom_param": "test"
      },
      "click_ids": {
        "gclid": "gclid_123",
        "fbclid": "fbclid_123",
        "fbc": "fb.1.1775958755156.fbclid_123"
      },
      "source": "google",
      "referer": "https://google.com/",
      "ip_address": "50.89.98.90",
      "ip_data": {
        "ip": "50.89.98.90",
        "city": {
          "country": {
            "iso_code": "US",
            "names": {
              "en": "United States"
            }
          },
          "location": {
            "latitude": 28.53,
            "longitude": -81.4807,
            "time_zone": "America/New_York"
          }
        },
        "isp": {
          "isp": "Spectrum",
          "organization": "Spectrum"
        }
      },
      "device_data": {
        "model": "iPhone",
        "os": {
          "name": "iOS",
          "version": "17.2"
        },
        "client": {
          "name": "Mobile Safari",
          "version": "17.2"
        },
        "is_mobile": true,
        "is_desktop": false
      },
      "client_attributes": {
        "locale": "en-US",
        "timezone": "America/New_York",
        "screenWidth": 1179,
        "screenHeight": 2556,
        "viewportWidth": 393,
        "viewportHeight": 852
      },
      "user_attributes": {
        "plan": "pro",
        "signup_step": "landing"
      },
      "custom_data": {
        "landing_variant": "v2",
        "widget_position": "hero"
      },
      "created_at": "2026-04-12T01:52:35.000000Z",
      "updated_at": "2026-04-12T01:52:35.000000Z"
    },
    "attributes": {
      "crm_id": "lead_2048",
      "plan": "pro"
    },
    "events": [
      {
        "id": 18,
        "uuid": "b19412c6-6a91-4e18-890d-e2269a0d1249",
        "name": "checkout_started",
        "attributes": {
          "cart_value": 129.99,
          "currency": "USD"
        },
        "occurred_at": "2026-04-12T02:10:00.000000Z"
      }
    ],
    "meta": {
      "uuid": "b19412c6-6a91-4e18-890d-e2269a0d1249",
      "events_limit": 100,
      "events_count": 1,
      "sort": "desc"
    }
  }
}

200 OK
{
  "success": true,
  "data": [
    {
      "id": 18,
      "session_id": 2,
      "uuid": "b19412c6-6a91-4e18-890d-e2269a0d1249",
      "name": "checkout_started",
      "attributes": {
        "cart_value": 129.99,
        "currency": "USD"
      },
      "ip_address": "50.89.98.90",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_2_1 like Mac OS X)",
      "occurred_at": "2026-04-12T02:10:00.000000Z",
      "created_at": "2026-04-12T02:10:01.000000Z",
      "updated_at": "2026-04-12T02:10:01.000000Z"
    }
  ],
  "meta": {
    "name": "checkout_started",
    "sort": "desc",
    "per_page": 25,
    "current_page": 1,
    "last_page": 1,
    "from": 1,
    "to": 1,
    "total": 1
  }
}

Auto-Captured Fields

Frontend SDKs can auto-capture useful client-side fields so you do not have to pass them manually every time.

  • userAgent
  • locale, language, languages
  • timezone, timezoneOffsetMinutes
  • screenWidth, screenHeight
  • viewportWidth, viewportHeight
  • pixelRatio, colorDepth
  • platform, touchPoints
  • cookiesEnabled
  • deviceMemoryGb
  • hardwareConcurrency
  • connectionType, connectionEffectiveType
  • connectionDownlinkMbps, connectionRttMs

FAQ

Yes. The SDK may generate a UUID, persist it client-side, and let you fetch it later through the SDK getter so you can associate it with your own user model.

Yes. track supports an optional UUID override so you can emit events from a different service layer where the user or session identifier is already known.

Yes. Server-side SDKs can send values such as IP address, user agent, referer, locale, and raw URL that are already known to your server at request time.