Impressions API Reference | 4D Sight Docs

Base URL and Versioning

All API traffic is served from https://api.4dsight.com over TLS 1.3. Versioning is path-based: the current stable version is /v1. Breaking changes ship under a new path segment; additive changes ship under the existing version without notice. Deprecated endpoints continue to serve traffic for a minimum of twelve months after the successor version is generally available.

Authentication

Every request must include a bearer token issued from the partner console:

Authorization: Bearer $API_KEY

Keys are scoped to a single workspace and a single environment (live or sandbox). Sandbox keys cannot read live data; live keys cannot write to sandbox. Rotate keys from the console — the platform supports overlapping validity windows so rotation never requires downtime. Compromised keys can be revoked instantly; the revocation propagates to all edge nodes within 60 seconds.

POST /v1/impressions

The write endpoint accepts a single impression event or an array up to 500 events per call. Requests must include Content-Type: application/json and an Idempotency-Key header — duplicate keys within a 24-hour window return the original response without re-processing, making safe retries trivial.

Request schema

event_id (string, required) — caller-supplied unique identifier; reused for idempotency.
broadcast (string, required) — broadcast identifier from the rights-holder feed catalog.
placement (string, required) — surface identifier (e.g. canvas_center, perimeter_north).
sponsor (string, required) — sponsor identifier from the creative library.
region (string, required) — ISO 3166-1 alpha-2 country code or a configured regional cluster.
viewability_pct (number 0–100, required) — continuous viewability as defined in the methodology doc.
on_screen_ms (integer, required) — total milliseconds the placement was on screen during this impression window.
surface_px (integer, required) — rendered surface area in pixels before occlusion.
occlusion_pct (number 0–100, optional) — share of surface pixels blocked by foreground elements.
brand_safety (enum: approved | flagged | blocked, optional) — populated by the brand safety classifier.

Response

Successful writes return 202 Accepted with the accepted event identifiers and a server-side ingest timestamp. The event is durable at this point; downstream materialization to the query store typically completes within 5 seconds and is bounded at 30 seconds p99.

GET /v1/impressions

The query endpoint supports filtering by broadcast, sponsor, region, placement, and a time window (from, to). Results are cursor-paginated via page_token; do not page by offset. The default page size is 200, the maximum is 1000. Server-side aggregations (sum, mean, percentile) are available via the companion /v1/impressions:aggregate endpoint and are typically the right call for dashboards — paging through raw events to compute totals client-side is an anti-pattern.

Rate Limits

Writes are limited to 10,000 events per second per workspace, burstable to 25,000 for 30 seconds. Reads are limited to 1,000 requests per second per workspace. Limits return 429 Too Many Requests with a Retry-After header in seconds. Production workloads should respect Retry-After and exponentially back off — clients that ignore the header are subject to circuit-breaking.

Errors

The API uses standard HTTP semantics: 2xx for success, 4xx for client errors, 5xx for server errors. Every error response includes a JSON body with error.code, error.message, and error.request_id. Always log request_id — every support case starts there.

SDKs

Official SDKs are published for TypeScript, Python, Go, and Java. Each SDK handles authentication, retry with exponential backoff, idempotency-key generation, and cursor pagination. Use the SDK unless your stack requires direct HTTP — the platform contract is identical, but the failure modes are pre-handled.