Conventions

Dates

Analytical endpoints take a date_range, in the property's time zone:

{ "date_range": { "start": "2026-10-01", "end": "2026-10-28" } }

or a preset: "today", "yesterday", "last_7_days", "last_28_days", "last_90_days" (complete days ending yesterday), "this_month", "last_month". On GET endpoints, pass date_range=<preset> or start= and end= in the query string.

Add "compare": "previous_period", "previous_year" or an explicit {start, end} range to get comparison values. Ranges older than your plan's history are shortened to what the plan covers; the response says so in meta.retention_floor.

Actor filter

"actor": "all" | "humans_and_agents" | "humans" | "action_agents" | "indexing_bots" | "mixed_sessions" (default all). See the overview.

Pagination

List endpoints take ?limit= and ?cursor= and return:

{ "data": [ … ], "next_cursor": "eyJvIjo1MH0" }

limit defaults to 50 (maximum 200). Pass next_cursor as cursor to get the next page; it is null on the last page.

Errors

Errors use application/problem+json (RFC 9457):

{
  "type": "https://docs.eureka-analytics.com/api/conventions#errors",
  "title": "Plan required",
  "status": 402,
  "detail": "Raw exports are available on the Pro plan.",
  "instance": "/v1/properties/AH-1A2B3C/exports/events",
  "code": "plan_required",
  "required_plan": "pro"
}

Status	code	Meaning
400	invalid_request	Invalid body or parameters; details in errors[]
401	unauthorized	Missing, invalid or revoked key
402	plan_required	The feature needs a higher plan (required_plan, feature)
403	forbidden_scope	The key lacks the scope (required_scope)
404	not_found	Unknown resource, or a property the key cannot access
429	rate_limited	Too many requests; see Retry-After
429	quota_exceeded	Monthly AI questions used up
500	internal	Our fault; retry later

Rate limits

Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. A 429 carries Retry-After (seconds). Limits per key: Pro 600/min, Scale 3,000/min, MCP keys 120/min.

Idempotency

Write requests accept an Idempotency-Key header. Retrying with the same key within 24 hours replays the first response (with the header Idempotent-Replayed: true) instead of acting twice. Use it for event ingestion and configuration changes.