{ "openapi": "3.0.3", "info": { "title": "Beam Analytics API", "version": "1.2.0", "description": "Start with metadata, discover websites and dimension values, then query analytics. Keys are read-only, workspace-scoped, and never expire. Docs: /docs/beam-api.md" }, "servers": [ { "url": "https://beam.experiment.sh" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "beam_sk_" } }, "schemas": { "Filter": { "oneOf": [ { "type": "object", "properties": { "field": { "type": "string", "enum": [ "page", "domain", "referrer", "browser", "operating_system", "country", "region", "city", "device_size", "utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term", "title", "hash", "continent", "isp", "event" ] }, "operator": { "type": "string", "enum": [ "is", "is_not", "contains", "not_contains", "starts_with", "not_starts_with" ] }, "value": { "type": "string", "maxLength": 500, "description": "Literal case-sensitive substring; no control characters or backslashes." } }, "required": [ "field", "operator", "value" ], "additionalProperties": false }, { "type": "object", "properties": { "field": { "type": "string", "enum": [ "page", "domain", "referrer", "browser", "operating_system", "country", "region", "city", "device_size", "utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term", "title", "hash", "continent", "isp", "event" ] }, "operator": { "type": "string", "enum": [ "is_set", "is_not_set" ] } }, "required": [ "field", "operator" ], "additionalProperties": false } ] }, "SummaryRequest": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z)?$", "description": "UTC YYYY-MM-DD or ISO timestamp ending in Z; from inclusive, to exclusive." }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z)?$", "description": "UTC YYYY-MM-DD or ISO timestamp ending in Z; from inclusive, to exclusive." }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/Filter" }, "maxItems": 20 }, "report": { "type": "string", "enum": [ "summary" ] }, "granularity": { "type": "string", "enum": [ "hour", "day", "week", "month" ], "default": "day", "description": "Used only for time series. Hourly ranges max 31 days; other ranges max 366 days. Empty buckets omitted." } }, "required": [ "report" ], "additionalProperties": false }, "TimeseriesRequest": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z)?$", "description": "UTC YYYY-MM-DD or ISO timestamp ending in Z; from inclusive, to exclusive." }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z)?$", "description": "UTC YYYY-MM-DD or ISO timestamp ending in Z; from inclusive, to exclusive." }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/Filter" }, "maxItems": 20 }, "report": { "type": "string", "enum": [ "timeseries" ], "default": "timeseries" }, "granularity": { "type": "string", "enum": [ "hour", "day", "week", "month" ], "default": "day", "description": "Used only for time series. Hourly ranges max 31 days; other ranges max 366 days. Empty buckets omitted." }, "fill": { "type": "string", "enum": [ "omit", "zero" ], "default": "omit" } }, "required": [], "additionalProperties": false }, "BreakdownRequest": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z)?$", "description": "UTC YYYY-MM-DD or ISO timestamp ending in Z; from inclusive, to exclusive." }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z)?$", "description": "UTC YYYY-MM-DD or ISO timestamp ending in Z; from inclusive, to exclusive." }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/Filter" }, "maxItems": 20 }, "report": { "type": "string", "enum": [ "breakdown" ] }, "granularity": { "type": "string", "enum": [ "hour", "day", "week", "month" ], "default": "day", "description": "Used only for time series. Hourly ranges max 31 days; other ranges max 366 days. Empty buckets omitted." }, "dimension": { "type": "string", "enum": [ "page", "domain", "referrer", "browser", "operating_system", "country", "region", "city", "device_size", "utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term", "title", "hash", "continent", "isp", "event" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "default": 0 }, "order_by": { "type": "string", "enum": [ "pageviews", "visits", "bounce_rate", "avg_session_sec" ], "default": "pageviews" }, "order": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "min_visits": { "type": "integer", "minimum": 0, "default": 0 } }, "required": [ "report", "dimension" ], "additionalProperties": false }, "QueryRequest": { "oneOf": [ { "$ref": "#/components/schemas/SummaryRequest" }, { "$ref": "#/components/schemas/TimeseriesRequest" }, { "$ref": "#/components/schemas/BreakdownRequest" } ] }, "ValuesRequest": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z)?$", "description": "UTC YYYY-MM-DD or ISO timestamp ending in Z; from inclusive, to exclusive." }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z)?$", "description": "UTC YYYY-MM-DD or ISO timestamp ending in Z; from inclusive, to exclusive." }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/Filter" }, "maxItems": 20 }, "field": { "type": "string", "enum": [ "page", "domain", "referrer", "browser", "operating_system", "country", "region", "city", "device_size", "utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term", "title", "hash", "continent", "isp", "event" ] }, "search": { "type": "string", "maxLength": 500, "description": "Literal case-sensitive substring; no control characters or backslashes." }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "default": 0 } }, "required": [ "field" ], "additionalProperties": false }, "Pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 0 }, "offset": { "type": "integer", "minimum": 0 }, "has_more": { "type": "boolean" }, "next_offset": { "type": "integer", "minimum": 0, "nullable": true } }, "required": [ "limit", "offset", "has_more", "next_offset" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false }, "SummaryRow": { "type": "object", "properties": { "pageviews": { "oneOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" } ], "description": "Number of matching analytics events, following Beam's dashboard convention." }, "visits": { "oneOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" } ], "description": "Distinct matching sessions. Time-series sessions are counted separately per bucket, not deduplicated across the range." }, "bounce_rate": { "oneOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" } ], "description": "Percentage of matching sessions with exactly one matching event." }, "avg_session_sec": { "oneOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" } ], "description": "Mean time between each matching session's first and last matching event." } }, "required": [ "pageviews", "visits", "bounce_rate", "avg_session_sec" ], "additionalProperties": false }, "TimeseriesRow": { "type": "object", "properties": { "pageviews": { "oneOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" } ], "description": "Number of matching analytics events, following Beam's dashboard convention." }, "visits": { "oneOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" } ], "description": "Distinct matching sessions. Time-series sessions are counted separately per bucket, not deduplicated across the range." }, "bounce_rate": { "oneOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" } ], "description": "Percentage of matching sessions with exactly one matching event." }, "avg_session_sec": { "oneOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" } ], "description": "Mean time between each matching session's first and last matching event." }, "date": { "type": "string", "format": "date-time" }, "incomplete": { "type": "boolean" }, "observed": { "type": "boolean" } }, "required": [ "pageviews", "visits", "bounce_rate", "avg_session_sec", "date", "incomplete", "observed" ], "additionalProperties": false }, "ValueRow": { "type": "object", "properties": { "value": { "type": "string", "nullable": true }, "pageviews": { "oneOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" } ], "description": "Backend numbers may be JSON numbers or numeric strings." }, "visits": { "oneOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" } ], "description": "Backend numbers may be JSON numbers or numeric strings." } }, "required": [ "value", "pageviews", "visits" ], "additionalProperties": false }, "BreakdownRow": { "type": "object", "properties": { "value": { "type": "string", "nullable": true }, "pageviews": { "oneOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" } ], "description": "Number of matching analytics events, following Beam's dashboard convention." }, "visits": { "oneOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" } ], "description": "Distinct matching sessions. Time-series sessions are counted separately per bucket, not deduplicated across the range." }, "bounce_rate": { "oneOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" } ], "description": "Percentage of matching sessions with exactly one matching event." }, "avg_session_sec": { "oneOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" } ], "description": "Mean time between each matching session's first and last matching event." } }, "required": [ "value", "pageviews", "visits", "bounce_rate", "avg_session_sec" ], "additionalProperties": false }, "WebsiteRow": { "type": "object", "properties": { "domain": { "type": "string" }, "pageviews": { "oneOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" } ], "description": "Backend numbers may be JSON numbers or numeric strings." }, "visits": { "oneOf": [ { "type": "number" }, { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" } ], "description": "Backend numbers may be JSON numbers or numeric strings." }, "first_seen": { "type": "string", "format": "date-time" }, "last_seen": { "type": "string", "format": "date-time" } }, "required": [ "domain", "pageviews", "visits", "first_seen", "last_seen" ], "additionalProperties": false }, "SummaryResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SummaryRow" } }, "meta": { "type": "object", "properties": { "workspace_id": { "type": "string" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "timezone": { "type": "string", "enum": [ "UTC" ] }, "report": { "type": "string", "enum": [ "summary" ] } }, "required": [ "workspace_id", "from", "to", "timezone", "report" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false }, "TimeseriesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TimeseriesRow" } }, "meta": { "type": "object", "properties": { "workspace_id": { "type": "string" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "timezone": { "type": "string", "enum": [ "UTC" ] }, "report": { "type": "string", "enum": [ "timeseries" ] }, "fill": { "type": "string", "enum": [ "omit", "zero" ] }, "granularity": { "type": "string", "enum": [ "hour", "day", "week", "month" ] } }, "required": [ "workspace_id", "from", "to", "timezone", "report", "fill", "granularity" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false }, "BreakdownResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BreakdownRow" } }, "meta": { "type": "object", "properties": { "workspace_id": { "type": "string" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "timezone": { "type": "string", "enum": [ "UTC" ] }, "report": { "type": "string", "enum": [ "breakdown" ] }, "dimension": { "type": "string", "enum": [ "page", "domain", "referrer", "browser", "operating_system", "country", "region", "city", "device_size", "utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term", "title", "hash", "continent", "isp", "event" ] }, "limit": { "type": "integer", "minimum": 0 }, "offset": { "type": "integer", "minimum": 0 }, "order_by": { "type": "string" }, "order": { "type": "string" }, "min_visits": { "type": "integer", "minimum": 0 } }, "required": [ "workspace_id", "from", "to", "timezone", "report", "dimension", "limit", "offset", "order_by", "order", "min_visits" ], "additionalProperties": false }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "meta", "pagination" ], "additionalProperties": false }, "QueryResponse": { "oneOf": [ { "$ref": "#/components/schemas/SummaryResponse" }, { "$ref": "#/components/schemas/TimeseriesResponse" }, { "$ref": "#/components/schemas/BreakdownResponse" } ] }, "ValuesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ValueRow" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "type": "object", "properties": { "workspace_id": { "type": "string" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "timezone": { "type": "string", "enum": [ "UTC" ] }, "field": { "type": "string", "enum": [ "page", "domain", "referrer", "browser", "operating_system", "country", "region", "city", "device_size", "utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term", "title", "hash", "continent", "isp", "event" ] }, "search": { "type": "string", "nullable": true }, "limit": { "type": "integer", "minimum": 0 }, "offset": { "type": "integer", "minimum": 0 } }, "required": [ "workspace_id", "from", "to", "timezone", "field", "search", "limit", "offset" ], "additionalProperties": false } }, "required": [ "data", "pagination", "meta" ], "additionalProperties": false }, "WebsitesResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebsiteRow" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "meta": { "type": "object", "properties": { "workspace_id": { "type": "string" }, "from": { "type": "string", "format": "date-time", "nullable": true }, "to": { "type": "string", "format": "date-time" }, "timezone": { "type": "string", "enum": [ "UTC" ] }, "source": { "type": "string", "enum": [ "observed_events" ] }, "search": { "type": "string", "nullable": true }, "limit": { "type": "integer", "minimum": 0 }, "offset": { "type": "integer", "minimum": 0 } }, "required": [ "workspace_id", "from", "to", "timezone", "source", "search", "limit", "offset" ], "additionalProperties": false } }, "required": [ "data", "pagination", "meta" ], "additionalProperties": false }, "MetadataResponse": { "type": "object", "properties": { "version": { "type": "string" }, "server_time": { "type": "string", "format": "date-time" }, "recommended_periods": { "type": "object", "properties": { "current": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "required": [ "from", "to" ], "additionalProperties": false }, "previous": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "required": [ "from", "to" ], "additionalProperties": false }, "description": { "type": "string" } }, "required": [ "current", "previous", "description" ], "additionalProperties": false }, "analysis_guide": { "type": "object", "properties": { "workflow": { "type": "array", "items": { "type": "string" } }, "measurement": { "type": "object", "properties": { "pageviews": { "type": "string" }, "visits": { "type": "string" }, "uid": { "type": "string" }, "attribution": { "type": "string" }, "devices": { "type": "string" }, "location": { "type": "string" }, "collection": { "type": "string" } }, "required": [ "pageviews", "visits", "uid", "attribution", "devices", "location", "collection" ], "additionalProperties": false }, "interpretation": { "type": "array", "items": { "type": "string" } }, "unsupported": { "type": "array", "items": { "type": "string" } } }, "required": [ "workflow", "measurement", "interpretation", "unsupported" ], "additionalProperties": false }, "workspace": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "access": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "analytics:read" ] }, "all_workspace_domains": { "type": "boolean" }, "expires": { "type": "boolean" } }, "required": [ "scope", "all_workspace_domains", "expires" ], "additionalProperties": false }, "timezone": { "type": "string", "enum": [ "UTC" ] }, "reports": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "metrics": { "type": "array", "items": { "type": "string" } }, "requires_dimension": { "type": "boolean" }, "paginated": { "type": "boolean" } }, "required": [ "id", "description", "metrics", "requires_dimension", "paginated" ], "additionalProperties": false } }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "unit": { "type": "string" }, "description": { "type": "string" } }, "required": [ "id", "type", "unit", "description" ], "additionalProperties": false } }, "dimensions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "page", "domain", "referrer", "browser", "operating_system", "country", "region", "city", "device_size", "utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term", "title", "hash", "continent", "isp", "event" ] }, "label": { "type": "string" }, "type": { "type": "string" }, "nullable": { "type": "boolean" }, "filterable": { "type": "boolean" }, "breakdown": { "type": "boolean" }, "values_endpoint": { "type": "string" }, "operators": { "type": "array", "items": { "type": "string", "enum": [ "is", "is_not", "contains", "not_contains", "starts_with", "not_starts_with", "is_set", "is_not_set" ] } } }, "required": [ "id", "label", "type", "nullable", "filterable", "breakdown", "values_endpoint", "operators" ], "additionalProperties": false } }, "filter_operators": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "is", "is_not", "contains", "not_contains", "starts_with", "not_starts_with", "is_set", "is_not_set" ] }, "requires_value": { "type": "boolean" }, "description": { "type": "string" } }, "required": [ "id", "requires_value", "description" ], "additionalProperties": false } }, "filter_semantics": { "type": "object", "properties": { "combination": { "type": "string" }, "case_sensitive": { "type": "boolean" }, "wildcard_characters_are_literal": { "type": "boolean" }, "max_value_length": { "type": "integer", "minimum": 0 }, "nulls": { "type": "string" }, "unsupported_value_characters": { "type": "string" } }, "required": [ "combination", "case_sensitive", "wildcard_characters_are_literal", "max_value_length", "nulls", "unsupported_value_characters" ], "additionalProperties": false }, "dates": { "type": "object", "properties": { "precision": { "type": "string" }, "from_inclusive": { "type": "boolean" }, "to_exclusive": { "type": "boolean" }, "formats": { "type": "array", "items": { "type": "string" } }, "default_from": { "type": "string" }, "default_to": { "type": "string" }, "granularities": { "type": "array", "items": { "type": "string" } }, "default_granularity": { "type": "string" }, "week_starts_on": { "type": "string" }, "empty_timeseries_buckets": { "type": "string" }, "websites_default_range": { "type": "string" } }, "required": [ "precision", "from_inclusive", "to_exclusive", "formats", "default_from", "default_to", "granularities", "default_granularity", "week_starts_on", "empty_timeseries_buckets", "websites_default_range" ], "additionalProperties": false }, "limits": { "type": "object", "properties": { "requests_per_minute_per_key": { "type": "integer", "minimum": 0 }, "body_bytes": { "type": "integer", "minimum": 0 }, "filters": { "type": "integer", "minimum": 0 }, "max_range_days": { "type": "integer", "minimum": 0 }, "hourly_max_range_days": { "type": "integer", "minimum": 0 }, "default_page_size": { "type": "integer", "minimum": 0 }, "max_page_size": { "type": "integer", "minimum": 0 }, "backend_timeout_seconds": { "type": "integer", "minimum": 0 }, "rate_limit_shared_across_endpoints": { "type": "boolean" }, "max_range_days_applies_to": { "type": "array", "items": { "type": "string" } } }, "required": [ "requests_per_minute_per_key", "body_bytes", "filters", "max_range_days", "hourly_max_range_days", "default_page_size", "max_page_size", "backend_timeout_seconds", "rate_limit_shared_across_endpoints", "max_range_days_applies_to" ], "additionalProperties": false }, "pagination": { "type": "object", "properties": { "endpoints": { "type": "array", "items": { "type": "string" } }, "input": { "type": "string" }, "continuation": { "type": "string" } }, "required": [ "endpoints", "input", "continuation" ], "additionalProperties": false }, "links": { "type": "object", "properties": { "entrypoint": { "type": "string" }, "coverage": { "type": "string" }, "compare": { "type": "string" }, "analysis": { "type": "string" }, "metadata": { "type": "string" }, "websites": { "type": "string" }, "values": { "type": "string" }, "query": { "type": "string" }, "docs": { "type": "string" }, "markdown": { "type": "string" }, "openapi": { "type": "string" } }, "required": [ "entrypoint", "coverage", "compare", "analysis", "metadata", "websites", "values", "query", "docs", "markdown", "openapi" ], "additionalProperties": false } }, "required": [ "version", "server_time", "recommended_periods", "analysis_guide", "workspace", "access", "timezone", "reports", "metrics", "dimensions", "filter_operators", "filter_semantics", "dates", "limits", "pagination", "links" ], "additionalProperties": false }, "CoverageRequest": { "type": "object", "properties": { "filters": { "type": "array", "items": { "$ref": "#/components/schemas/Filter" }, "maxItems": 20 } }, "required": [], "additionalProperties": false }, "CoverageResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "events": { "type": "integer", "minimum": 0 }, "visits": { "type": "integer", "minimum": 0 }, "days_with_events": { "type": "integer", "minimum": 0 }, "events_without_session_id": { "type": "integer", "minimum": 0 }, "events_without_domain": { "type": "integer", "minimum": 0 }, "first_seen": { "type": "string", "format": "date-time", "nullable": true }, "last_seen": { "type": "string", "format": "date-time", "nullable": true }, "elapsed_seconds_since_last_event": { "type": "integer", "minimum": 0, "nullable": true }, "ingestion_complete_through": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "events", "visits", "days_with_events", "events_without_session_id", "events_without_domain", "first_seen", "last_seen", "elapsed_seconds_since_last_event", "ingestion_complete_through" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "workspace_id": { "type": "string" }, "timezone": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "scope": { "type": "string" }, "caveat": { "type": "string" } }, "required": [ "workspace_id", "timezone", "generated_at", "scope", "caveat" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false }, "CompareRequest": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z)?$", "description": "UTC YYYY-MM-DD or ISO timestamp ending in Z; from inclusive, to exclusive." }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z)?$", "description": "UTC YYYY-MM-DD or ISO timestamp ending in Z; from inclusive, to exclusive." }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/Filter" }, "maxItems": 20 }, "compare_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z)?$", "description": "UTC YYYY-MM-DD or ISO timestamp ending in Z; from inclusive, to exclusive." }, "compare_to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z)?$", "description": "UTC YYYY-MM-DD or ISO timestamp ending in Z; from inclusive, to exclusive." } }, "required": [], "additionalProperties": false }, "MetricChange": { "type": "object", "properties": { "current": { "type": "number" }, "previous": { "type": "number" }, "absolute_change": { "type": "number", "nullable": true }, "percent_change": { "type": "number", "nullable": true }, "absolute_change_unit": { "type": "string", "enum": [ "events", "sessions", "percentage_points", "seconds" ] } }, "required": [ "current", "previous", "absolute_change", "percent_change", "absolute_change_unit" ], "additionalProperties": false }, "CompareResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "pageviews": { "$ref": "#/components/schemas/MetricChange" }, "visits": { "$ref": "#/components/schemas/MetricChange" }, "bounce_rate": { "$ref": "#/components/schemas/MetricChange" }, "avg_session_sec": { "$ref": "#/components/schemas/MetricChange" } }, "required": [ "pageviews", "visits", "bounce_rate", "avg_session_sec" ], "additionalProperties": false }, "meta": { "type": "object", "properties": { "workspace_id": { "type": "string" }, "timezone": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "current": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "required": [ "from", "to" ], "additionalProperties": false }, "previous": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "required": [ "from", "to" ], "additionalProperties": false }, "caveat": { "type": "string" } }, "required": [ "workspace_id", "timezone", "generated_at", "current", "previous", "caveat" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false }, "EntrypointResponse": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "base_url": { "type": "string" }, "authentication": { "type": "object", "properties": { "type": { "type": "string" }, "header": { "type": "string" }, "scope": { "type": "string" }, "expires": { "type": "boolean" } }, "required": [ "type", "header", "scope", "expires" ], "additionalProperties": false }, "start_here": { "type": "string" }, "workflow": { "type": "array", "items": { "type": "string" } }, "links": { "type": "object", "properties": { "metadata": { "type": "string" }, "websites": { "type": "string" }, "values": { "type": "string" }, "coverage": { "type": "string" }, "compare": { "type": "string" }, "query": { "type": "string" }, "docs": { "type": "string" }, "analysis": { "type": "string" }, "openapi": { "type": "string" } }, "required": [ "metadata", "websites", "values", "coverage", "compare", "query", "docs", "analysis", "openapi" ], "additionalProperties": false } }, "required": [ "name", "version", "base_url", "authentication", "start_here", "workflow", "links" ], "additionalProperties": false } } }, "paths": { "/api/v1": { "get": { "operationId": "getApiEntrypoint", "summary": "Public starting URL, authentication instructions and workflow links", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntrypointResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No queryable retained dataset; do not interpret as zero traffic", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Use the method specified in Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "schema": { "type": "string" } } } }, "413": { "description": "Body exceeds 16 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "Use application/json for POST", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Shared key rate limit reached; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 0 }, "description": "Seconds until the next rate window." } } }, "502": { "description": "Backend unavailable; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/api/v1/coverage": { "post": { "operationId": "getDataCoverage", "summary": "Inspect retained event bounds and missing identifiers for selected filters", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverageResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No queryable retained dataset; do not interpret as zero traffic", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Use the method specified in Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "schema": { "type": "string" } } } }, "413": { "description": "Body exceeds 16 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "Use application/json for POST", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Shared key rate limit reached; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 0 }, "description": "Seconds until the next rate window." } } }, "502": { "description": "Backend unavailable; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverageRequest" } } } } } }, "/api/v1/compare": { "post": { "operationId": "comparePeriods", "summary": "Compare equal-duration, non-overlapping periods; defaults to completed UTC days", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompareResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No queryable retained dataset; do not interpret as zero traffic", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Use the method specified in Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "schema": { "type": "string" } } } }, "413": { "description": "Body exceeds 16 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "Use application/json for POST", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Shared key rate limit reached; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 0 }, "description": "Seconds until the next rate window." } } }, "502": { "description": "Backend unavailable; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompareRequest" } } } } } }, "/api/v1/metadata": { "get": { "operationId": "getMetadata", "summary": "Identify the workspace and discover API capabilities, filter types, metrics, and limits", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No queryable retained dataset; do not interpret as zero traffic", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Use the method specified in Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "schema": { "type": "string" } } } }, "413": { "description": "Body exceeds 16 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "Use application/json for POST", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Shared key rate limit reached; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 0 }, "description": "Seconds until the next rate window." } } }, "502": { "description": "Backend unavailable; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/websites": { "get": { "operationId": "listWebsites", "summary": "Discover observed websites across all retained history, alphabetically, with pagination", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsitesResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No queryable retained dataset; do not interpret as zero traffic", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Use the method specified in Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "schema": { "type": "string" } } } }, "413": { "description": "Body exceeds 16 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "Use application/json for POST", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Shared key rate limit reached; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 0 }, "description": "Seconds until the next rate window." } } }, "502": { "description": "Backend unavailable; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z)?$", "description": "UTC YYYY-MM-DD or ISO timestamp ending in Z; from inclusive, to exclusive." }, "required": false }, { "name": "to", "in": "query", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}(?:T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z)?$", "description": "UTC YYYY-MM-DD or ISO timestamp ending in Z; from inclusive, to exclusive." }, "required": false }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 500, "description": "Literal case-sensitive substring; no control characters or backslashes." }, "required": false }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 }, "required": false }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "default": 0 }, "required": false } ] } }, "/api/v1/values": { "post": { "operationId": "listFilterValues", "summary": "Discover observed dimension values within a date range and filters", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValuesResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No queryable retained dataset; do not interpret as zero traffic", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Use the method specified in Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "schema": { "type": "string" } } } }, "413": { "description": "Body exceeds 16 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "Use application/json for POST", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Shared key rate limit reached; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 0 }, "description": "Seconds until the next rate window." } } }, "502": { "description": "Backend unavailable; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValuesRequest" } } } } } }, "/api/v1/query": { "post": { "operationId": "queryAnalytics", "summary": "Query summaries, time series, or paginated breakdowns", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryResponse" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Workspace unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No queryable retained dataset; do not interpret as zero traffic", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Use the method specified in Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Allow": { "schema": { "type": "string" } } } }, "413": { "description": "Body exceeds 16 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } }, "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "Use application/json for POST", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Shared key rate limit reached; honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 0 }, "description": "Seconds until the next rate window." } } }, "502": { "description": "Backend unavailable; retry with backoff", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" } } } } } } } }