> 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.09.16"},"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."}},"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":{"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":[{"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":{"description":"Analytics summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OverviewResponse"}}}},"400":{"description":"Invalid time window","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"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.09.16"},"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."}},"schemas":{"WebhookDeliveriesResponse":{"type":"object","required":["deliveries"],"properties":{"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"next_cursor":{"type":"string","description":"Pass as ?cursor= for the next page; absent 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":{"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":[{"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,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","required":false,"description":"event_id from the previous page's next_cursor","schema":{"type":"string"}}],"responses":{"200":{"description":"One page of delivery outcomes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveriesResponse"}}}},"400":{"description":"Invalid pagination or filter parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Missing or invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"503":{"description":"Current authorization is unavailable; retry after the dependency recovers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}}}}
```