Data Collections Read API

AudienceExternal API Consumers, Integrators

Required PermissionsCollection Direct API Key or Share API Key

Estimated Time6 min read

Demo Referencecemento-valladolid

The Data Collections API (data-collections-api) exposes curated, alias-only read endpoints for published Data Collections.

Authentication Headers

Send both headers on every request:

• X-API-Key: Your collection API key ID
• X-API-Secret: Your collection API secret

Keys are scoped strictly to a single collection ({public_id}). For share keys, the collection must be Active, the share must be active with can_use_api enabled, and snapshot/latest calls require streaming/window grants as configured by the owner.

Endpoints

Method & Path	Description
GET /api/v1/collections/{public_id}	Return collection metadata and curated tag catalog with aliases and units.
GET /api/v1/collections/{public_id}/tags?limit=100&offset=0	Paginated tag metadata ordered by sort_order (limit 1–1000).
GET /api/v1/collections/{public_id}/snapshot	Latest value (ok, no_data, or error), timestamp, and quality for every tag in the collection.
GET /api/v1/collections/{public_id}/tags/{tag_public_id}/latest	Latest reading for one collection-scoped tag UUID (tag_public_id).

Common HTTP Status Codes

Status	Meaning
200 OK	Request succeeded; response includes UTC timestamp.
401 Unauthorized	Missing, invalid, or expired API key/secret.
403 Forbidden	Key bound to a different collection, collection is Paused (for share keys), or share grant/window denied.
404 Not Found	Collection or tag UUID does not exist.
410 Gone	Collection is Archived (all keys permanently revoked).
422 Unprocessable Entity	Invalid UUID or pagination query parameter.
503 / 504	Auth/upstream dependency unavailable or delegated deadline exceeded.

Related Guides

• Data Collections Guide
• Data Collection Lifecycle