API Reference
Start typing to search…
  1. DELIVR RESOLUTIONS & EVENTS API

Delivr Resolutions & Events Data API — Overview

The Delivr Events Data API provides access to pixel events and, when needed, identity-enriched person/company attributes

Basic Information

  • Base URL: https://apiv2.delivr.ai
  • Format: JSON (UTF-8)
  • Authentication: header X-API-Key: <your_key>
  • Time window limit: end - start <= 25 hours

Endpoint Overview

  • GET /api/v1/events - fetch events with support for filters (filter), projections (select), deduplication (distinct), and pagination (offset/limit).
  • GET /api/v1/event_counts - aggregated event counts; supports filter and unique counting with distinct.
  • GET /api/v1/events_schema - list of available fields (name, type, nullable) for dynamic query building.

Request Parameters

Scope (one required)

You must provide ONE of the following to scope your query:

  • pixel_id (string, uuid) - Query events for a specific pixel. example: pixel_id=7b63468b-c4f2-4c3c-02d5-c82f977cf308

  • project_id (string, uuid) - Query events across all pixels in a project (organization). example: project_id=1d7b5e3c-7a9e-4e31-91a8-0b2d9f2b7a10

  • organization_id (string, uuid) - Query events across all pixels in a master organization. example: organization_id=a2e1f8a8-1b3a-4c1c-9c0f-2b6a1d9f3f11

Priority: If multiple are provided, pixel_id takes precedence over project_id, which takes precedence over organization_id.

Time Range (required)

Choose ONE format for specifying the time range:

Option A: Milliseconds (recommended for programmatic use)

  • start_ms (integer, int64) - Start of interval in Unix Epoch milliseconds.
  • end_ms (integer, int64) - End of interval in Unix Epoch milliseconds. example: start_ms=1759492800000&end_ms=1759496400000

Option B: Human-readable (convenient for manual queries)

  • start_time (string) - Start of interval. Accepts RFC3339, YYYY-MM-DD, or Unix timestamp.
  • end_time (string) - End of interval. Accepts RFC3339, YYYY-MM-DD, or Unix timestamp. examples:
    • start_time=2024-01-15&end_time=2024-01-16
    • start_time=2024-01-15T00:00:00Z&end_time=2024-01-15T23:59:59Z

Pagination (only /api/v1/events)

  • offset (integer, >= 0, default 0) - Number of records to skip.
  • limit (integer, 1...1000, default 100) - Page size.

Projections and Filters

  • select (string, comma-separated) - List of fields to return. example: select=email,first_name,last_name

  • filter (string, comma-separated) - Filter expressions in the form field:op:value. Operators: eq, ne, gt, gte, lt, lte, like. examples:

    • filter=resolved:eq:true - Only identity-enriched events
    • filter=event_type:eq:purchase

  • distinct (string, comma-separated) - Fields for deduplication/unique counting. examples:

    • distinct=email
    • distinct=email,cookie_id

Rules and Limitations

  • Time window: The interval between start and end must not exceed 25 hours.
  • Pagination: Use offset and limit for paging; valid limit range is 1...1000.
  • Filters: Format is field:op:value; URL-encode colons and special characters if present.
  • Deduplication: The distinct parameter removes duplicates by the specified fields and affects the result of /api/v1/event_counts.
  • Authentication: Every request must include the X-API-Key header; invalid keys result in 401 Unauthorized.
  • Rate limiting: On 429 Too Many Requests, reduce request frequency and honor Retry-After.