API reference
Complete reference for all Lab Reports API endpoints.
Base URL: https://access.tryterra.co/api
All endpoints require the following headers:
dev-id
string
Yes
Your Terra developer ID
x-api-key
string
Yes
Your Terra API key
X-Terra-Version
string
No
The API version to serve the request in, as a YYYY-MM-DD date. See Versioning.
Errors use the RFC 7807 Problem JSON format. When an error carries a machine-readable code, branch on it rather than on detail, which is written for people and can change.
{
"type": "about:blank",
"title": "bad request",
"detail": "file 0 is text/plain; upload a PDF or a PNG, JPEG, GIF, WebP or HEIC image",
"instance": "/api/v2/reports",
"code": "unsupported_file_type"
}Versioning
The Lab Reports API is versioned by date. Only the List Sessions response differs between versions.
2026-10-21
Latest. The list is paginated: limit and cursor parameters, and a data, has_more, next_cursor response.
2026-03-24
The original shape. The list returns up to 500 sessions in sessions, with no pagination.
Each request is served in one version, picked in this order:
The
X-Terra-Versionheader, if you send one. It takes a date and serves the newest version on or before it. A date before2026-03-24serves2026-03-24.Your environment's pinned version.
The latest version, if your environment has no pin.
Environments that used Lab Reports before 2026-10-21 was released, or whose account already had Lab Reports enabled, are pinned to 2026-03-24. Existing integrations keep the list shape they were built against. An environment without a pin is pinned to the latest version on its first API request, so it keeps that version when a newer one is released.
Every authenticated response carries an X-Terra-Version header stating the version it was served in. A malformed date, or a date in the future, returns 400 with code invalid_api_version.
Webhook deliveries carry an X-Terra-Version header with your environment's pinned version. See Webhook payload.
Changing your pinned version
To move an environment to the paginated list:
Send
X-Terra-Version: 2026-10-21on your list requests, and update your code to readdataand follownext_cursor.Change the pin, so requests without the header get the new version too. With the Terra CLI:
The change takes effect on the environment's next request. A GET on the same path shows the current pin, the latest version, and every version you can pin to. Changing the pin needs the dataconfig:write scope. You can move the pin back to 2026-03-24 the same way. A pin cannot be removed.
Upload a lab report
POST /v2/reports
Upload one report for processing, as multipart form data. Send the report as one file, or as one file per page, in page order. Accepted formats: PDF, PNG, JPEG, GIF, WebP and HEIC/HEIF.
Headers
dev-id
Your developer ID
x-api-key
Your API key
Content-Type
multipart/form-data
Query parameters
reference_id
string
No
Your external identifier for this report/patient
Request body (multipart)
file
file
Yes
A file of the report: a PDF, or a PNG, JPEG, GIF, WebP or HEIC/HEIF image. Repeat the part, up to 20 times, to send the pages of one report in order.
The form field name is file (singular) for every part. Each part needs a filename, which curl's -F "file=@..." sends for you.
Terra identifies each file's type from its contents, not from its name or declared Content-Type. A photo saved as image.jpg that is really a HEIC is read as a HEIC.
Limits
Files per upload
20, the pages of one report
File size
20 MB per file
Upload size
50 MB in total
PDF size
22.5 MB of PDF in total per upload
Image size
64 megapixels for HEIC, HEIF, GIF and WebP; 256 megapixels for JPEG and PNG
An upload over the file, upload or PDF size limit is refused with 413. An image over its pixel limit is accepted, and the report then fails with file_too_large. A report whose files together are more than can be read as one report fails the same way. See Error Codes.
Files are stored exactly as uploaded. A HEIC photo keeps its EXIF metadata, including GPS location. Strip location data on the device before uploading if you do not want it stored.
Example
A report photographed page by page, sent as one upload:
Response: 202 Accepted
Error responses
Status
code
Description
400
validation_failed
No file part, an empty file, a part without a filename, or a malformed form
400
unsupported_file_type
A file is not a PDF or a supported image. detail names the type its contents show.
400
too_many_files
More than 20 files
401
Invalid or missing dev-id / x-api-key
403
entitlement_required
Lab Reports is not enabled for your account
413
payload_too_large
A file over 20 MB, an upload over 50 MB, or more than 22.5 MB of PDF
500
Internal server error
503
authorization_unavailable
Access could not be checked. Retry shortly.
List sessions
GET /v2/reports
List lab report sessions for your account, newest first, with optional filters. List items carry the summary fields only, without results or panels.
The response shape depends on the API version the request is served in.
Query parameters
limit
integer
No
Page size. Defaults to 50. A value above 200 is served as 200. From version 2026-10-21.
cursor
string
No
The previous page's next_cursor. From version 2026-10-21.
reference_id
string
No
Filter by your external reference ID
upload_id
string
No
Filter by the upload handle
report_type
string
No
Return only sessions of this kind: lab or dexa. Omit for both. Any other value is rejected with 400.
report_date_from
string
No
Lab report date lower bound (ISO-8601 YYYY-MM-DD)
report_date_to
string
No
Lab report date upper bound (ISO-8601 YYYY-MM-DD)
uploaded_at_from
string
No
Upload date lower bound (ISO-8601 YYYY-MM-DD)
uploaded_at_to
string
No
Upload date upper bound (ISO-8601 YYYY-MM-DD)
All date filters are inclusive and can be combined. For example, you can query "reports from January uploaded this week" by setting both report_date_from/report_date_to and uploaded_at_from/uploaded_at_to.
Example
Response: 200 OK (version 2026-10-21)
data
object[]
This page's sessions
has_more
boolean
Whether another page follows
next_cursor
string?
Pass it as cursor to get the next page. null on the last page.
To get the next page, repeat the request with the same filters and add cursor. A cursor is tied to the filters it was issued for: sending it with different filters returns 400 with code validation_failed. Treat the cursor as opaque.
Response: 200 OK (version 2026-03-24)
Up to 500 sessions in sessions, newest first, with no pagination. limit and cursor are ignored. Use the filters to narrow the list.
Error responses
Status
code
Description
400
An invalid report_type or date filter
400
validation_failed
An invalid limit, a malformed cursor, or a cursor sent with different filters
400
invalid_api_version
X-Terra-Version is not a date, or is in the future
401
Invalid or missing authentication
503
authorization_unavailable, service_unavailable
Temporarily unavailable. Retry.
Retrieve a session
GET /v2/reports/{session_id}
Retrieve the report: metadata, results, reference ranges, and status history. This response is immutable and cacheable. It does not include presigned file URLs (which expire) or per-destination delivery state (which changes). Fetch those from the sub-resources below.
Path parameters
session_id
string
Yes
The session's snowflake ID
Example
Response: 200 OK
See the Quickstart page for a complete example response. The session object is returned directly at the top level. Key fields include:
session_id: Snowflake ID (string)upload_id: The upload this report came from (string)reference_id: Your external reference (omitted if not set)current_status: Current status as a clean lowercase string (e.g."sent","processing")report_type: Report type (e.g."lab")report_date: Date from the lab report (YYYY-MM-DD string, omitted if not extracted)report_time: Time from the lab report (HH:MM 24-hour, omitted if not extracted)collection_date: Specimen collection date (YYYY-MM-DD string, omitted if not extracted)collection_time: Specimen collection time (HH:MM 24-hour, omitted if not extracted)uploaded_at: Session creation timestamp (ISO-8601)updated_at: Last update timestamp (ISO-8601)report_locale: Locale of the report (e.g."ja-JP","pt-BR")lab_name: Name of the laboratorypatient_sex: Clean lowercase string (e.g."male","female", omitted if unspecified)patient_age_at_collection: Patient age in years (integer, omitted if unknown)report_notes: Free-text notes extracted from the reporterror: Why the report failed, as{ code, message, retriable, document_class? }. The same object as the failure webhook. Present only whilecurrent_statusisfailed.status_history[]: Array of{ status, timestamp, note }entriesresults_count: Number of biomarker resultsfile_count: Number of uploaded filesinput_bytes: Size of uploaded file(s) in bytesoutput_bytes: Size of output data in bytespanels[]: Report-level panels that results reference bypanel_id(omitted if the report has no panel grouping)results[]: Array of biomarker results, each grouped intosource/biomarker/measurement/interpretationlayers (see Core concepts for field specs)
Error responses
401
Invalid or missing authentication
404
Session not found
500
Internal server error
List deliveries
GET /v2/reports/{session_id}/deliveries
The per-destination delivery state for a report. A report is fanned out to every destination that has opted in to lab reports (see Delivery destinations), and each is tracked independently, so a failure to one never hides that the report reached the others. This is also why a session can be partially_sent. Delivery state is mutable (pending → delivered/failed/retrying), so it lives here rather than on the cacheable session.
Response: 200 OK
destination_id
string
The destination's ID
destination_type
string
The destination's type (e.g. webhook, s3)
status
string
pending, delivered, or failed
attempt_count
integer
Retry count: 0 on the first attempt, incremented per retry
last_error
string?
Most recent delivery error (omitted when delivered)
List files
GET /v2/reports/{session_id}/files
The uploaded input files and the report thumbnail, with freshly minted presigned download URLs. URLs are issued on demand because they expire. They are not embedded in the cacheable session or the webhook.
Response: 200 OK
files lists the uploaded files in upload order, exactly as they were uploaded. Each is named by its position, not by the name it was sent with, and content_type is the type Terra detected from its contents.
expires_at applies to every URL in the response. URLs last at most one hour. Fetch the endpoint again to mint fresh URLs.
List artifacts
GET /v2/reports/{session_id}/artifacts
Intermediate processing artifacts, with freshly minted presigned URLs. Privileged keys only. Standard keys receive a 404. Same response shape as /files (an artifacts[] array plus expires_at).
Reprocess a session
POST /v2/reports/{session_id}/reprocess
Re-run extraction and standardization on an existing session, from the files it was uploaded with. Use it to retry a failed report whose error.retriable is true, or to pick up improvements in processing. When retriable is false, reprocessing the same files fails the same way: upload a new file instead.
Path parameters
session_id
string
Yes
The session's snowflake ID
Example
Response: 202 Accepted
Includes a Location header pointing to the session. The session re-enters the processing -> ... -> sent flow. A reprocess is a new run, so it ends in a new webhook event, lab_report.completed or lab_report.failed, with a new event_id.
Only finished sessions can be reprocessed: sent, partially_sent, delivery_failed or failed. Each session can be reprocessed up to 3 times. A report that was already billed is not billed again.
Error responses
Status
code
Description
401
Invalid or missing authentication
403
entitlement_required
Lab Reports is not enabled for your account
404
Session not found
409
The session is still processing, or was cancelled
409
reprocess_limit_reached
The session has been reprocessed 3 times already
500
Internal server error
Delete a session
DELETE /v2/reports/{session_id}
Delete a report. It is removed from the API immediately: every endpoint returns 404 for it afterwards, and it is no longer listed. Delete works even if your Lab Reports access has ended.
What happens to the data:
Files, results and the copies Terra keeps are erased from active systems within 30 days. The target is 24 hours.
Backup copies are kept only for disaster recovery, and expire within 10 days.
File URLs already issued by List Files keep working until they expire, at most one hour after they were issued.
Copies delivered to your destinations are yours. Delete them from your webhook store, bucket or database yourself.
Reports you do not delete are kept until you delete them or close your account.
Path parameters
session_id
string
Yes
The session's snowflake ID
Example
Response: 204 No Content
No response body.
Error responses
401
Invalid or missing authentication
404
Session not found, or already deleted
500
Internal server error
Last updated
Was this helpful?