> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/reference/vantage-api/analytics.md).

# Analytics

## Analytics overview

> Client-scoped analytics summary for a time window: order totals with a by-status breakdown, results in vs. still missing, and webhook failures with a daily series.

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"servers":[{"url":"https://vantage.tryterra.co"}],"security":[{"BasicAuth":[]},{"DataBearer":[],"DevIDHeader":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic","description":"Authenticate with your Terra API credentials: username = your Terra\n`dev-id`, password = your Terra API key — the same credentials used for\nevery other Terra API. The header pair `dev-id` + `x-api-key` is also\naccepted. Suspended credentials receive 403; accounts without the\nVantage entitlement receive 403 once entitlement enforcement is\nenabled. Once the credential validator is configured, backfilled keys\nalso honor current token expiry, revocation, audience and Vantage scopes.\nInvalid tokens receive 401, insufficient scopes 403 and an unavailable\nvalidator 503. These checks remain active when product policy is off.\n"},"DataBearer":{"type":"http","scheme":"bearer","bearerFormat":"Terra data token","description":"A data-plane token with vantage:read for reads or vantage:write for writes. Requires dev-id. Write includes read; data:read alone does not grant Vantage. Available after the API credential validator is configured."}},"parameters":{"ApiVersion":{"name":"X-Terra-Version","in":"header","required":false,"description":"The API version to serve this request in. Defaults to your account's pinned version; an account is pinned to the latest version on its first request.","schema":{"type":"string","enum":["2026-09-27","2026-10-01","2026-10-15"]}}},"headers":{"ApiVersion":{"description":"The API version this response was rendered in.","schema":{"type":"string","enum":["2026-09-27","2026-10-01","2026-10-15"]}},"RequestId":{"description":"A UUID generated for this request, unique per request and never taken from the caller. Quote it to support to find the request.","schema":{"type":"string","format":"uuid"}}},"schemas":{"OverviewResponse":{"type":"object","required":["orders","results","webhooks"],"properties":{"orders":{"type":"object","required":["total","by_status"],"properties":{"total":{"type":"integer"},"by_status":{"type":"object","additionalProperties":{"type":"integer"},"description":"Order counts keyed by current fulfilment status string."}}},"results":{"type":"object","required":["total","missing"],"properties":{"total":{"type":"integer"},"missing":{"type":"integer"}}},"webhooks":{"type":"object","required":["failed_total","daily"],"properties":{"failed_total":{"type":"integer"},"daily":{"type":"array","items":{"type":"object","required":["date","failed"],"properties":{"date":{"type":"string"},"failed":{"type":"integer"}}}}}}}},"ProblemDetail":{"description":"Standard error response format following RFC 7807 specification","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}}}}},"paths":{"/api/v1/overview":{"get":{"operationId":"getOverview","summary":"Analytics overview","tags":["analytics"],"description":"Client-scoped analytics summary for a time window: order totals with a by-status breakdown, results in vs. still missing, and webhook failures with a daily series.","parameters":[{"$ref":"#/components/parameters/ApiVersion"},{"name":"since","in":"query","required":false,"description":"Start of the window (RFC3339). Defaults to until minus 7 days.","schema":{"type":"string","format":"date-time"}},{"name":"until","in":"query","required":false,"description":"End of the window (RFC3339). Defaults to now.","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Analytics summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OverviewResponse"}}}},"400":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Invalid time window. An unsupported `X-Terra-Version` also returns 400 with code `invalid_api_version`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Current authorization is unavailable; retry after the dependency recovers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}}}}
```

## List webhook delivery outcomes

> Client-scoped keyset list of terminal webhook delivery outcomes, newest first. Use outcome=failed to see only permanently-failed deliveries.

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"servers":[{"url":"https://vantage.tryterra.co"}],"security":[{"BasicAuth":[]},{"DataBearer":[],"DevIDHeader":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic","description":"Authenticate with your Terra API credentials: username = your Terra\n`dev-id`, password = your Terra API key — the same credentials used for\nevery other Terra API. The header pair `dev-id` + `x-api-key` is also\naccepted. Suspended credentials receive 403; accounts without the\nVantage entitlement receive 403 once entitlement enforcement is\nenabled. Once the credential validator is configured, backfilled keys\nalso honor current token expiry, revocation, audience and Vantage scopes.\nInvalid tokens receive 401, insufficient scopes 403 and an unavailable\nvalidator 503. These checks remain active when product policy is off.\n"},"DataBearer":{"type":"http","scheme":"bearer","bearerFormat":"Terra data token","description":"A data-plane token with vantage:read for reads or vantage:write for writes. Requires dev-id. Write includes read; data:read alone does not grant Vantage. Available after the API credential validator is configured."}},"parameters":{"ApiVersion":{"name":"X-Terra-Version","in":"header","required":false,"description":"The API version to serve this request in. Defaults to your account's pinned version; an account is pinned to the latest version on its first request.","schema":{"type":"string","enum":["2026-09-27","2026-10-01","2026-10-15"]}}},"headers":{"ApiVersion":{"description":"The API version this response was rendered in.","schema":{"type":"string","enum":["2026-09-27","2026-10-01","2026-10-15"]}},"RequestId":{"description":"A UUID generated for this request, unique per request and never taken from the caller. Quote it to support to find the request.","schema":{"type":"string","format":"uuid"}}},"schemas":{"WebhookDeliveriesResponse":{"type":"object","description":"One page of webhook delivery outcomes, newest first. Versions before 2026-10-15 serve the items under `deliveries` instead of `data`, no `has_more`, and omit `next_cursor` on the last page.","required":["data","has_more","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as ?cursor= for the next page; null on the last page."}}},"WebhookDelivery":{"type":"object","required":["event_id","event_type","order_id","order_item_id","outcome","final_status_code","attempts","completed_at","event_created_at"],"properties":{"event_id":{"type":"string"},"event_type":{"type":"string","description":"Same vocabulary as the webhook event_type field (currently order.status_changed, order_item.status_changed and order_item.results_status_change). Open set - new event types may appear; treat unknown values as deliveries of a newer event family."},"order_id":{"type":"string"},"order_item_id":{"type":"string"},"outcome":{"type":"string","description":"One of: delivered, rejected, invalid, dead_lettered, replayed."},"final_status_code":{"type":["integer","null"]},"attempts":{"type":"integer"},"completed_at":{"type":"string","format":"date-time"},"event_created_at":{"type":"string","format":"date-time"}}},"ProblemDetail":{"description":"Standard error response format following RFC 7807 specification","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}}}}},"paths":{"/api/v1/webhook-deliveries":{"get":{"operationId":"listWebhookDeliveries","summary":"List webhook delivery outcomes","tags":["analytics"],"description":"Client-scoped keyset list of terminal webhook delivery outcomes, newest first. Use outcome=failed to see only permanently-failed deliveries.","parameters":[{"$ref":"#/components/parameters/ApiVersion"},{"name":"outcome","in":"query","required":false,"description":"One delivery outcome, or \"failed\" (rejected|invalid|dead_lettered).","schema":{"type":"string","enum":["delivered","rejected","invalid","dead_lettered","replayed","failed"]}},{"name":"limit","in":"query","required":false,"description":"Page size. Values above 100 are treated as 100.","schema":{"type":"integer","minimum":1,"default":25}},{"name":"cursor","in":"query","required":false,"description":"event_id from the previous page's next_cursor","schema":{"type":"string"}}],"responses":{"200":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"One page of delivery outcomes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveriesResponse"}}}},"400":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Invalid pagination or filter parameters. An unsupported `X-Terra-Version` also returns 400 with code `invalid_api_version`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Current authorization is unavailable; retry after the dependency recovers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}}}}
```