Analytics Endpoints

The analytics endpoints let you export raw click and scan event data from Codelloy. Use them to build custom dashboards, feed data warehouses, or integrate with your existing analytics stack.

Authentication

All analytics endpoints use X-API-KEY header authentication:

curl -H "X-API-KEY: your_api_key_here" \
  "https://api.codelloy.com/link/external/v1/analytics/events"

See Authentication and Obtaining Your API Key for details.

List Analytics Events

GET /link/external/v1/analytics/events

Returns raw click and scan events with cursor-based pagination. Supports two modes: Browse and Sync.

Mode Detection

The API automatically selects a mode based on the parameters you provide:

Note: Browse mode requires both from and to parameters. Omitting them will return an error.

You cannot combine Browse and Sync parameters in the same request. Providing both from/to and since will return an error.

Browse Mode

Query events within a date range. Useful for ad-hoc analysis and backfills.

Parameters:

Example:

curl -H "X-API-KEY: your_api_key_here" \
  "https://api.codelloy.com/link/external/v1/analytics/events?from=2026-01-01&to=2026-01-31&limit=500"

Response:

{
  "data": [
    {
      "eventId": "evt_abc123",
      "shortCode": "my-link",
      "schemaVersion": 1,
      "createdAt": "2026-01-15T10:30:00Z",
      "shortUrlId": "url_abc123",
      "eventType": "CLICK",
      "clickSource": "DIRECT",
      "referrer": "https://facebook.com",
      "referrerDomain": "facebook.com",
      "country": "United States",
      "countryCode": "US",
      "city": "San Francisco",
      "region": "California",
      "browserName": "Chrome",
      "browserVersion": "122.0",
      "osName": "iOS",
      "osVersion": "17.4",
      "deviceType": "MOBILE",
      "deviceBrand": "Apple",
      "deviceModel": "iPhone",
      "utmSource": "facebook",
      "utmMedium": "social",
      "utmCampaign": "launch"
    }
  ],
  "hasMore": true,
  "nextCursor": "cursor_xyz789"
}

To fetch the next page, pass nextCursor as the cursor parameter:

curl -H "X-API-KEY: your_api_key_here" \
  "https://api.codelloy.com/link/external/v1/analytics/events?from=2026-01-01&to=2026-01-31&cursor=cursor_xyz789"

Sync Mode

Incrementally fetch new events since a given point in time. Designed for data warehouse ingestion pipelines that run on a schedule.

Parameters:

Example:

curl -H "X-API-KEY: your_api_key_here" \
  "https://api.codelloy.com/link/external/v1/analytics/events?since=2026-03-01T00:00:00Z"

Response:

{
  "data": [ ... ],
  "hasMore": false,
  "nextSince": "2026-03-15T14:22:00Z",
  "afterEventId": "evt_def456"
}

On your next sync run, use the returned nextSince and afterEventId values:

curl -H "X-API-KEY: your_api_key_here" \
  "https://api.codelloy.com/link/external/v1/analytics/events?since=2026-03-15T14:22:00Z&afterEventId=evt_def456"

Event Fields

Each event object contains the following fields:

Export Events

GET /link/external/v1/analytics/events/export

Download all events as a file. The export endpoint only supports Browse mode — you must provide from and to parameters. The since parameter (Sync mode) is not allowed on the export endpoint.

Additional parameter:

Example — CSV export:

curl -H "X-API-KEY: your_api_key_here" \
  "https://api.codelloy.com/link/external/v1/analytics/events/export?from=2026-01-01&to=2026-03-31&format=csv" \
  -o analytics.csv

Example — JSON export:

curl -H "X-API-KEY: your_api_key_here" \
  "https://api.codelloy.com/link/external/v1/analytics/events/export?from=2026-01-01&to=2026-03-31&format=json" \
  -o analytics.ndjson

The JSON export uses newline-delimited JSON (one JSON object per line), making it easy to stream into BigQuery, Snowflake, or similar tools.

Rate Limits

Analytics endpoints have separate rate limits from the link management API:

When you exceed the limit, you will receive a 429 Too Many Requests response. See Rate Limiting for best practices.

Best Practices

1. Use Sync mode for pipelines — If you are ingesting data into a warehouse on a schedule, Sync mode ensures you never miss events and never process duplicates.

2. Use Browse mode for ad-hoc queries — When you need data for a specific date range, Browse mode is more straightforward.

3. Store nextSince and afterEventId — After each sync run, persist these values so your next run picks up exactly where you left off.

4. Use CSV for spreadsheets, JSON for pipelines — CSV is convenient for quick analysis in Excel or Google Sheets. Newline-delimited JSON is better for programmatic ingestion.

5. Respect rate limits — Space out export requests and use pagination for large date ranges rather than exporting everything at once.