> 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

An overview of your Vantage activity, and the outcome of each webhook delivery.

## Analytics overview

> Summarises your Vantage activity over a time window: order totals by fulfilment status, results in and still missing, and failed webhook deliveries with a daily series.\
> \
> \- Like \`GET /api/v1/orders\` and \`GET /api/v1/results\`, every count covers the environment's current Vantage access or, without it, only its verified purchases.

```json
{"openapi":"3.2.0","info":{"title":"Terra Vantage API","version":"2026.11.11.1"},"tags":[{"name":"analytics","summary":"Analytics","description":"An overview of your Vantage activity, and the outcome of each webhook delivery."}],"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."},"DevIDHeader":{"type":"apiKey","in":"header","name":"dev-id","description":"Environment owned by the data token's customer and within its audience."}},"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","2026-10-29"]}}},"headers":{"ApiVersion":{"description":"The API version this response was rendered in.","schema":{"type":"string","enum":["2026-09-27","2026-10-01","2026-10-15","2026-10-29"]}},"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"}}},"Refusal":{"description":"A credential refusal from Terra's edge, served as `application/problem+json` in every version. The HTTP status is not repeated in the body.","type":"object","required":["type","title","instance","detail","code"],"properties":{"type":{"type":"string"},"title":{"type":"string","description":"The HTTP status text, lowercased."},"instance":{"type":"string","description":"The request path, with its query."},"detail":{"type":"string"},"code":{"type":"string","description":"Why the credential was refused: `unauthorized` (401) for a missing, invalid, expired or revoked credential; `scope_missing` (403) for one that lacks the scope this operation requires; `audience_restricted` (403) for one not granted for this dev-id; `authorization_unavailable` (503) when the credential could not be checked, so retry later.","enum":["unauthorized","scope_missing","audience_restricted","authorization_unavailable"]}}}}},"paths":{"/api/v1/overview":{"get":{"operationId":"getOverview","summary":"Analytics overview","tags":["analytics"],"description":"Summarises your Vantage activity over a time window: order totals by fulfilment status, results in and still missing, and failed webhook deliveries with a daily series.\n\n- Like `GET /api/v1/orders` and `GET /api/v1/results`, every count covers the environment's current Vantage access or, without it, only its verified purchases.","parameters":[{"$ref":"#/components/parameters/ApiVersion"},{"name":"since","in":"query","required":false,"description":"Start of the window (RFC 3339). Defaults to 7 days before `until`.","schema":{"type":"string","format":"date-time"}},{"name":"until","in":"query","required":false,"description":"End of the window (RFC 3339). 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"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}},"403":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"The credential lacks the scope this operation requires (code `scope_missing`) or is not granted for this dev-id (code `audience_restricted`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}},"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"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}}}}}}}
```

## List webhook delivery outcomes

> Lists the final outcome of each webhook delivery, newest first, one page at a time.\
> \
> \- A resend from \`POST /api/v1/webhook-events/resend\` replaces the event's earlier outcome.

```json
{"openapi":"3.2.0","info":{"title":"Terra Vantage API","version":"2026.11.11.1"},"tags":[{"name":"analytics","summary":"Analytics","description":"An overview of your Vantage activity, and the outcome of each webhook delivery."}],"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."},"DevIDHeader":{"type":"apiKey","in":"header","name":"dev-id","description":"Environment owned by the data token's customer and within its audience."}},"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","2026-10-29"]}}},"headers":{"ApiVersion":{"description":"The API version this response was rendered in.","schema":{"type":"string","enum":["2026-09-27","2026-10-01","2026-10-15","2026-10-29"]}},"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"}}},"Refusal":{"description":"A credential refusal from Terra's edge, served as `application/problem+json` in every version. The HTTP status is not repeated in the body.","type":"object","required":["type","title","instance","detail","code"],"properties":{"type":{"type":"string"},"title":{"type":"string","description":"The HTTP status text, lowercased."},"instance":{"type":"string","description":"The request path, with its query."},"detail":{"type":"string"},"code":{"type":"string","description":"Why the credential was refused: `unauthorized` (401) for a missing, invalid, expired or revoked credential; `scope_missing` (403) for one that lacks the scope this operation requires; `audience_restricted` (403) for one not granted for this dev-id; `authorization_unavailable` (503) when the credential could not be checked, so retry later.","enum":["unauthorized","scope_missing","audience_restricted","authorization_unavailable"]}}}}},"paths":{"/api/v1/webhook-deliveries":{"get":{"operationId":"listWebhookDeliveries","summary":"List webhook delivery outcomes","tags":["analytics"],"description":"Lists the final outcome of each webhook delivery, newest first, one page at a time.\n\n- A resend from `POST /api/v1/webhook-events/resend` replaces the event's earlier outcome.","parameters":[{"$ref":"#/components/parameters/ApiVersion"},{"name":"outcome","in":"query","required":false,"description":"Only deliveries with this outcome. `failed` matches every permanently failed delivery: `rejected`, `invalid` and `dead_lettered`.","schema":{"type":"string","enum":["delivered","rejected","invalid","dead_lettered","replayed","failed"]}},{"name":"limit","in":"query","required":false,"description":"Deliveries per page. Defaults to 25; a value above 100 is treated as 100.","schema":{"type":"integer","minimum":1,"default":25}},{"name":"cursor","in":"query","required":false,"description":"The `next_cursor` from the previous page, an `event_id`.","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"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}},"403":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"The credential lacks the scope this operation requires (code `scope_missing`) or is not granted for this dev-id (code `audience_restricted`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}},"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"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}}}}}}}
```
