Skip to main content
POST /v1/homology takes a query, a target release, and what evidence you want back. The computation is durable — it is accepted, then retrieved, then paged — so a long search survives a dropped connection and the same request never runs twice.

​
Run a computation

target.database_release_id pins an immutable release, so the same request always searches the same bytes. List what you can search with GET /v1/homology_databases. results states what you are asking for, not how to compute it:
  • evidence — pairwise_sequence_alignment for exact alignments, or candidate_measurement for unverified candidates.
  • max_results — how many targets to materialize.
  • significance_requirement — not_requested, if_available, or required. required fails the computation rather than returning uncalibrated results.
Optional: constraints (deadline_ms, max_billable_units), policy.id to pin an exact search policy, and target.filter to restrict the searched documents.

​
Wait, or don’t

The Prefer header controls the transport only — never the science: You get 201 Created when the computation is already terminal, or 202 Accepted with a Location header while work remains. Either way the body is the same object, and Preference-Applied echoes what the server honored.

​
Retrieve and page

status moves queued → running → succeeded | failed. On success the object carries a result_set summary, the receipt (what the engine actually read), policy_id, the target space it resolved, and specification_sha256 — the content address of the computation itself, which is what makes a rerun identifiable as the same question. Results are paged separately, because a result set can be large:
Pass the previous page’s cursor as starting_after to continue.

​
Read the result

Each result carries named measurements, not a single score — alignment geometry, identity counts, and, when requested and available, calibrated significance. Nothing in the response says “these are homologs”: the engine reports what it measured and against which release, and the caller draws the conclusion.
Every response is the standard envelope. Read warnings — that is where a truncated result set, an unavailable significance model, or an exhausted budget is reported.