Results

List results

get

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

Authorizations

AuthorizationstringRequired

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.

Query parameters

limitinteger · min: 1 · max: 100OptionalDefault: 25

cursorstringOptional

order_item_id from the previous page's next_cursor

Example: 333410942627700737

statusstringOptional

Filter by results status string (e.g. results.results_ready)

Responses

200

One page of results

application/json

next_cursorstringOptional

Pass as ?cursor= for the next page; absent on the last page.

Example: 333410942627700737

400

Invalid pagination or filter parameters

application/json

401

Missing or invalid credentials

application/json

500

Internal server error

application/json

get/api/v1/results

GET /api/v1/results HTTP/1.1
Host: vantage.tryterra.co
Authorization: Basic username:password
Accept: */*

{
  "results": [
    {
      "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"
    }
  ],
  "next_cursor": "333410942627700737"
}

Get presigned URL for test results

get

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.

Authorizations

AuthorizationstringRequired

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.

Path parameters

orderItemIDinteger · min: 1Required

Order Item ID

Query parameters

test_taker_idinteger · min: 1Required

Test Taker ID

Responses

200

Successfully generated download URL

application/json

Response containing a presigned URL to download test results

download_urlstringOptionalExample: https://storage.googleapis.com/bucket/results/123.json?signature=abc123

expires_atstringOptionalExample: 2025-10-23T18:00:00Z

formatstring · enumOptionalExample: jsonPossible values:

400

Invalid or missing order item ID

application/json

401

Unauthorized - invalid client credentials

application/json

404

Results not found for this order item

application/json

500

Internal server error

application/json

get/api/v1/results/{orderItemID}

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"
}

Acknowledge results receipt

post

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.

Authorizations

AuthorizationstringRequired

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.

Path parameters

orderItemIDinteger · min: 1Required

Order Item ID

Query parameters

test_taker_idinteger · min: 1Required

Test Taker ID

Responses

200

Results acknowledged successfully

application/json

Confirmation that results were acknowledged

statusstringOptionalExample: acknowledged

400

Invalid order item ID

application/json

401

Unauthorized - invalid credentials

application/json

404

Order item not found

application/json

500

Internal server error

application/json

post/api/v1/results/{orderItemID}/acknowledge

POST /api/v1/results/{orderItemID}/acknowledge?test_taker_id=1 HTTP/1.1
Host: vantage.tryterra.co
Authorization: Basic username:password
Accept: */*

{
  "status": "acknowledged"
}