> 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/results.md).

# Results

List results, fetch a result file, and record each test taker's confirmation that they received their result.

## List results

> Lists order items with result activity, newest first, one page at a time.\
> \
> \- Filters combine: a result must match every filter given, and any one of a list filter's values.

```json
{"openapi":"3.2.0","info":{"title":"Terra Vantage API","version":"2026.11.11.1"},"tags":[{"name":"results","summary":"Results","description":"List results, fetch a result file, and record each test taker's confirmation that they received their result."}],"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","2026-10-29"]}},"ListOrder":{"name":"order","in":"query","required":false,"description":"Sort direction: `desc` for newest first, `asc` for oldest first. Defaults to `desc`; send the same value with every page's cursor.","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}}},"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":{"ListResultsResponse":{"type":"object","description":"One page of order items with result activity, newest first. Versions before 2026-10-15 serve the items under `results` 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/ResultSummary"}},"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."}}},"ResultSummary":{"type":"object","required":["order_item_id","order_id","variant_id","results_status","is_acknowledged","updated_at"],"properties":{"order_item_id":{"type":"string"},"order_id":{"type":"string"},"variant_id":{"type":"string"},"product_name":{"type":"string"},"results_status":{"type":"string"},"is_acknowledged":{"type":"boolean"},"test_taker_id":{"type":"string"},"updated_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/results":{"get":{"operationId":"listResults","summary":"List results","tags":["results"],"description":"Lists order items with result activity, newest first, one page at a time.\n\n- Filters combine: a result must match every filter given, and any one of a list filter's values.","parameters":[{"$ref":"#/components/parameters/ApiVersion"},{"name":"limit","in":"query","required":false,"description":"Results 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 `order_item_id`. Send it with the same `order` and filters as that page.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Only results whose results status is one of these, such as `results.results_ready`. Repeat the parameter or join the statuses with commas; an unknown status returns 400. Acknowledgement is not a status: filter on it with `is_acknowledged`.","schema":{"type":"array","items":{"type":"string"}}},{"name":"variant_id","in":"query","required":false,"description":"Only results for these product variants. Repeat the parameter or join the ids with commas; at most 100.","schema":{"type":"array","maxItems":100,"items":{"type":"string"}}},{"name":"client_order_reference_id","in":"query","required":false,"description":"Only results of the order with exactly this `client_order_reference_id`.","schema":{"type":"string"}},{"$ref":"#/components/parameters/ListOrder"},{"name":"is_acknowledged","in":"query","required":false,"description":"Only results you have (true) or have not (false) acknowledged.","schema":{"type":"boolean"}},{"name":"order_id","in":"query","required":false,"description":"Only items of these orders. Repeat the parameter or join the ids with commas; at most 100. An id that is no order matches nothing.","schema":{"type":"array","maxItems":100,"items":{"type":"string"}}},{"name":"since","in":"query","required":false,"description":"Only items whose `updated_at` is at or after this time (RFC 3339).","schema":{"type":"string","format":"date-time"}},{"name":"until","in":"query","required":false,"description":"Only items whose `updated_at` is at or before this time (RFC 3339).","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"One page of results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListResultsResponse"}}}},"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"}}}}}}}}}
```

## Get presigned URL for test results

> Returns a short-lived URL to download an order item's normalised result as JSON: a FHIR R4 bundle for a blood test, a Terra DNA result for a DNA test.\
> \
> \- The URL expires at \`expires\_at\`, at most 45 seconds after the request was authorised and sooner if your token expires first. Request a fresh URL each time you start a download.\
> \- An order item has at most one panel, so its id identifies the result.

```json
{"openapi":"3.2.0","info":{"title":"Terra Vantage API","version":"2026.11.11.1"},"tags":[{"name":"results","summary":"Results","description":"List results, fetch a result file, and record each test taker's confirmation that they received their result."}],"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","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":{"GetResultsURLResponse":{"description":"Response containing a presigned URL to download test results","type":"object","properties":{"download_url":{"type":"string"},"expires_at":{"type":"string"},"format":{"type":"string","enum":["json"]},"result_type":{"type":"string","description":"How to parse the downloaded file. `fhir_bundle` is a FHIR R4 Bundle (blood tests); `dna_result` is a Terra DNA result, plain JSON (DNA tests), described by the `DNAResult` schema. Non-exhaustive: new representations may be added without a new API version.","enum":["fhir_bundle","dna_result"]},"result_version":{"type":"integer","format":"int32","minimum":1,"description":"Version of the result the URL serves: 1 for the first result, bumped by every re-analysis (DNA). Matches `result_version` on the `results.results_ready` and `results.reanalysed` webhooks."}}},"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"}}},"AuthenticationError":{"description":"Authentication error response (401)","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}},"required":["detail","status","title","type"]},"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/results/{orderItemID}":{"get":{"operationId":"getResultsUrl","summary":"Get presigned URL for test results","tags":["results"],"description":"Returns a short-lived URL to download an order item's normalised result as JSON: a FHIR R4 bundle for a blood test, a Terra DNA result for a DNA test.\n\n- The URL expires at `expires_at`, at most 45 seconds after the request was authorised and sooner if your token expires first. Request a fresh URL each time you start a download.\n- An order item has at most one panel, so its id identifies the result.","parameters":[{"$ref":"#/components/parameters/ApiVersion"},{"name":"orderItemID","in":"path","description":"The order item's `order_item_id`.","required":true,"schema":{"type":"integer","minimum":1}},{"name":"test_taker_id","in":"query","description":"The order item's `test_taker_id`. Another test taker's id returns 400.","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Successfully generated download URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetResultsURLResponse"}}}},"400":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Invalid or missing order item ID. 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":"Unauthorized - invalid client credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}},"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"}}}},"404":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Results not found for this order item","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"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}}}}}}}
```

## Acknowledge results receipt

> Records that the test taker confirmed, in your app, that they received their result.\
> \
> \- Every result needs it, and it is never automatic: call it only from the test taker's own action, such as a button or checkbox after your app shows the result.\
> \- It is a legal requirement. Results left unacknowledged can get your Vantage access suspended, enforced within 1 to 5 business days.\
> \- An escalated result carries an \`acknowledgment\_due\_by\` deadline; if it is missed, the lab may contact the patient.

```json
{"openapi":"3.2.0","info":{"title":"Terra Vantage API","version":"2026.11.11.1"},"tags":[{"name":"results","summary":"Results","description":"List results, fetch a result file, and record each test taker's confirmation that they received their result."}],"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","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":{"AcknowledgeResultsResponse":{"description":"Confirmation that results were acknowledged","type":"object","properties":{"status":{"type":"string"}}},"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"}}},"AuthenticationError":{"description":"Authentication error response (401)","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}},"required":["detail","status","title","type"]},"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/results/{orderItemID}/acknowledge":{"post":{"operationId":"acknowledgeResults","summary":"Acknowledge results receipt","tags":["results"],"description":"Records that the test taker confirmed, in your app, that they received their result.\n\n- Every result needs it, and it is never automatic: call it only from the test taker's own action, such as a button or checkbox after your app shows the result.\n- It is a legal requirement. Results left unacknowledged can get your Vantage access suspended, enforced within 1 to 5 business days.\n- An escalated result carries an `acknowledgment_due_by` deadline; if it is missed, the lab may contact the patient.","parameters":[{"$ref":"#/components/parameters/ApiVersion"},{"name":"orderItemID","in":"path","description":"The order item's `order_item_id`.","required":true,"schema":{"type":"integer","minimum":1}},{"name":"test_taker_id","in":"query","description":"The order item's `test_taker_id`. Another test taker's id returns 400.","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Results acknowledged successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcknowledgeResultsResponse"}}}},"400":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Invalid order item ID. 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":"Unauthorized - invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}},"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"}}}},"404":{"headers":{"X-Terra-Version":{"$ref":"#/components/headers/ApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"description":"Order item not found","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"}},"application/problem+json":{"schema":{"$ref":"#/components/schemas/Refusal"}}}}}}}}}
```
