> 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/vantage-api-reference/core-resources/results.md).

# Results

## List results

> Keyset-paginated index of order items with result activity, newest first.

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"servers":[{"url":"https://vantage.tryterra.co"}],"security":[{"BasicAuth":[]}],"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.\n"}},"schemas":{"ListResultsResponse":{"type":"object","required":["results"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/ResultSummary"}},"next_cursor":{"type":"string","description":"Pass as ?cursor= for the next page; absent 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"}}}}},"paths":{"/api/v1/results":{"get":{"summary":"List results","tags":["results"],"description":"Keyset-paginated index of order items with result activity, newest first.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","required":false,"description":"order_item_id from the previous page's next_cursor","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by results status string (e.g. results.results_ready)","schema":{"type":"string"}}],"responses":{"200":{"description":"One page of results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListResultsResponse"}}}},"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"}}}}}}}}}
```

## Get presigned URL for test results

> Returns a time-limited presigned URL to download normalized test results in FHIR format (JSON). The URL is valid for 15 minutes. Note: Every orderItemID can only be associated with maximum 1 panel, hence results can be uniquely identified by orderItemID.

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"servers":[{"url":"https://vantage.tryterra.co"}],"security":[{"BasicAuth":[]}],"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.\n"}},"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"]}}},"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"]}}},"paths":{"/api/v1/results/{orderItemID}":{"get":{"summary":"Get presigned URL for test results","tags":["results"],"description":"Returns a time-limited presigned URL to download normalized test results in FHIR format (JSON). The URL is valid for 15 minutes. Note: Every orderItemID can only be associated with maximum 1 panel, hence results can be uniquely identified by orderItemID.","parameters":[{"name":"orderItemID","in":"path","description":"Order Item ID","required":true,"schema":{"type":"integer","minimum":1}},{"name":"test_taker_id","in":"query","description":"Test Taker ID","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Successfully generated download URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetResultsURLResponse"}}}},"400":{"description":"Invalid or missing order item ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Unauthorized - invalid client credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}}},"404":{"description":"Results not found for this order item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}}}}
```

## Acknowledge results receipt

> Records the end user's affirmative confirmation that they have received and viewed their results (Schedule C §C6A). Must be triggered by an explicit end-user action (e.g. a checkbox or button in the client's UI) — never automatically by the backend on retrieval or delivery. Required for compliance and audit trails.

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"servers":[{"url":"https://vantage.tryterra.co"}],"security":[{"BasicAuth":[]}],"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.\n"}},"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"]}}},"paths":{"/api/v1/results/{orderItemID}/acknowledge":{"post":{"summary":"Acknowledge results receipt","tags":["results"],"description":"Records the end user's affirmative confirmation that they have received and viewed their results (Schedule C §C6A). Must be triggered by an explicit end-user action (e.g. a checkbox or button in the client's UI) — never automatically by the backend on retrieval or delivery. Required for compliance and audit trails.","parameters":[{"name":"orderItemID","in":"path","description":"Order Item ID","required":true,"schema":{"type":"integer","minimum":1}},{"name":"test_taker_id","in":"query","description":"Test Taker ID","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Results acknowledged successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcknowledgeResultsResponse"}}}},"400":{"description":"Invalid order item ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"401":{"description":"Unauthorized - invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}}},"404":{"description":"Order item not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}}}}
```