Data API Quickstart

The Data API gives agencies, DSPs, and data partners read access to Trillboards audience intelligence: live audience snapshots, historical aggregations, semantic search over scene embeddings, and lookalike screen discovery. Use it for planning, attribution, and measurement workflows that do not need ad-serving control.

Base URL: https://api.trillboards.com

1. Get an API key

Data API keys have the prefix tb_dat_ and are issued from the portal. Keys are scoped; common scopes are read:live, read:historical, read:semantic, and stream:live. Each request must include the key in the X-API-Key header.

2. Make your first call

List the screens your key is authorized to see:


curl -s "https://api.trillboards.com/v1/data/screens?limit=5" \
  -H "X-API-Key: tb_dat_xxxxxxxxxxxx"

Success response:


{
  "screens": [
    { "screen_id": "...", "mongo_screen_id": "...", "name": "Lobby #3",
      "venue_type": "fitness", "city": "Brooklyn", "country": "US", "status": "active" }
  ],
  "count": 1, "offset": 0, "limit": 5
}

If the X-API-Key header is missing or invalid, you get the canonical error envelope:


{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid or inactive API key provided.",
    "request_id": "req_a1b2c3d4e5f6789012345678901234ab",
    "doc_url": "https://api.trillboards.com/docs/errors#invalid_api_key"
  }
}

Every 4xx/5xx response echoes error.request_id matching the X-Request-Id response header. Paste it into a support ticket and we can trace the request end-to-end.

3. Common errors

`error.code`	HTTP	How to fix
`authentication_required`	401	Add the `X-API-Key` header.
`invalid_api_key`	401	Check the key you copied from the portal. Rotate if compromised.
`insufficient_permissions`	403	Your key is missing a required scope (for example, `read:historical`). Request an upgrade from your account manager.
`rate_limit_exceeded`	429	Back off using the `Retry-After` header; default limit is 60 req/min per key.

Next steps

Full reference: /docs/data
Error catalog: /docs/errors
FEIN query DSL: POST /v1/data/query for composable dimensions + measures
Streaming: GET /v1/data/stream (Server-Sent Events, scope stream:live)