Results
Keyset-paginated index of order items with result activity, newest first.
Authenticate with your Terra API credentials: username = your Terra
dev-id, password = your Terra API key — the same credentials used for
every other Terra API. The header pair dev-id + x-api-key is also
accepted. Suspended credentials receive 403; accounts without the
Vantage entitlement receive 403 once entitlement enforcement is
enabled. Once the credential validator is configured, backfilled keys
also honor current token expiry, revocation, audience and Vantage scopes.
Invalid tokens receive 401, insufficient scopes 403 and an unavailable
validator 503. These checks remain active when product policy is off.
Page size. Values above 100 are treated as 100.
25order_item_id from the previous page's next_cursor
333410942627700737Filter by results status string (e.g. results.results_ready)
Only results you have (true) or have not (false) acknowledged.
Only items of this order.
333410942627700736Only items whose updated_at is at/after this RFC3339 timestamp.
Only items whose updated_at is at/before this RFC3339 timestamp.
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.
One page of results
Invalid pagination or filter parameters. An unsupported X-Terra-Version also returns 400 with code invalid_api_version.
Missing or invalid credentials
Internal server error
Current authorization is unavailable; retry after the dependency recovers.
GET /api/v1/results HTTP/1.1
Host: vantage.tryterra.co
Authorization: Basic username:password
Accept: */*
{
"data": [
{
"order_item_id": "333410942627700737",
"order_id": "333410942627700736",
"variant_id": "100011",
"product_name": "General Health",
"results_status": "results.results_ready",
"is_acknowledged": true,
"test_taker_id": "333410942627700738",
"updated_at": "2026-01-01T00:00:00.000Z"
}
],
"has_more": true,
"next_cursor": "333410942627700737"
}Returns a time-limited presigned URL to download normalized test results (JSON): a FHIR R4 bundle for blood tests, a Terra DNA result for DNA tests. result_type says which, and result_version which version of the result the URL serves. The URL is valid for 15 minutes before credential validation is configured. Validated requests receive a URL bounded by token expiry and the original authorization deadline (at most 45 seconds), even when product policy is off; request a fresh URL when starting each download. Note: Every orderItemID can only be associated with maximum 1 panel, hence results can be uniquely identified by orderItemID.
Authenticate with your Terra API credentials: username = your Terra
dev-id, password = your Terra API key — the same credentials used for
every other Terra API. The header pair dev-id + x-api-key is also
accepted. Suspended credentials receive 403; accounts without the
Vantage entitlement receive 403 once entitlement enforcement is
enabled. Once the credential validator is configured, backfilled keys
also honor current token expiry, revocation, audience and Vantage scopes.
Invalid tokens receive 401, insufficient scopes 403 and an unavailable
validator 503. These checks remain active when product policy is off.
Order Item ID
Test Taker ID
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.
Successfully generated download URL
Invalid or missing order item ID. An unsupported X-Terra-Version also returns 400 with code invalid_api_version.
Unauthorized - invalid client credentials
Results not found for this order item
Internal server error
Current authorization is unavailable; retry after the dependency recovers.
GET /api/v1/results/{orderItemID}?test_taker_id=1 HTTP/1.1
Host: vantage.tryterra.co
Authorization: Basic username:password
Accept: */*
{
"download_url": "https://storage.googleapis.com/bucket/results/123.json?signature=abc123",
"expires_at": "2025-10-23T18:00:00Z",
"format": "json",
"result_type": "fhir_bundle",
"result_version": 1
}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.
Authenticate with your Terra API credentials: username = your Terra
dev-id, password = your Terra API key — the same credentials used for
every other Terra API. The header pair dev-id + x-api-key is also
accepted. Suspended credentials receive 403; accounts without the
Vantage entitlement receive 403 once entitlement enforcement is
enabled. Once the credential validator is configured, backfilled keys
also honor current token expiry, revocation, audience and Vantage scopes.
Invalid tokens receive 401, insufficient scopes 403 and an unavailable
validator 503. These checks remain active when product policy is off.
Order Item ID
Test Taker ID
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.
Results acknowledged successfully
Invalid order item ID. An unsupported X-Terra-Version also returns 400 with code invalid_api_version.
Unauthorized - invalid credentials
Order item not found
Internal server error
Current authorization is unavailable; retry after the dependency recovers.
POST /api/v1/results/{orderItemID}/acknowledge?test_taker_id=1 HTTP/1.1
Host: vantage.tryterra.co
Authorization: Basic username:password
Accept: */*
{
"status": "acknowledged"
}Last updated
Was this helpful?