Get Source Discovery Results
Fetch the discovered first-mile locations of a completed source-discovery task
as a JSON:API collection. Call this once GET /discovery/source/{taskId}/status
reports status: completed.
Each item is a computed source_location with a candidate id. Discovery
finds facility locations and supply-chain leads, not verified plot boundaries.
Geometry can be null, including for an unresolved town-only candidate.
Never substitute a town centroid for a supplier's plot.
For ingestion, read ingestable, ingest_block_reason and to_ingest
alongside linkage, lineage, classification, pin status and imagery. A medium
confidence tier alone does not make a candidate ingestable. The server's
verdict reflects the requested linkage/confidence filters when supplied.
▶Request
▶Method & Path
GET /discovery/source/{taskId}/results
▶Path parameters
taskId(UUID, required) — the discovery task id. A non-UUID value is rejected with400.
▶Query parameters
linkage(string[], optional) andmin_confidence(high / medium / low, optional) — evaluate the ingestability verdict under these filters. Send the same filters to ingestion if you choose that gate; defaults stay strict.partial(true/false, optional) — serve the running task's newest provisional snapshot instead of a409.meta.partialis thentrue, and each candidate carriesprovisionalandgeneration.since_generation(integer ≥ 0, optional) — withpartial=true, return only the candidates that changed after this snapshot generation.meta.candidate_idslists every id in the snapshot, so a missing id means the candidate was removed. Ignored on a finished result.
▶Headers
x-api-key— required.Accept: application/json
▶Response
- 200 — a collection of
source_locationresources, with discovery metadata onmeta. An emptydataarray with ameta.warningmeans no commodity could be resolved/inferred or nothing cleared the evidence bar. - 400 —
taskIdis not a valid UUID. - 401 / 403 — missing or invalid key, or the key lacks
geocode:read. - 404 — the task is unknown or belongs to a different organization.
- 409 — the task is still processing; keep polling
…/status. - 502 — the discovery failed, or a transient upstream failure fetching the results.
▶Response schema — data[] (source_location)
data[] (source_location)| Field | Type | Description |
|---|---|---|
type | string | Always source_location. |
id | string | null | Stable candidate id used for decisions and ingestion; null for a legacy blob without ids (re-run discovery). |
attributes.name | string | Display name (node name, else address/company). |
attributes.supplier_name | string | null | Discovered node/operator name; null when undocumented. |
attributes.address | string | null | Locality, admin area, country. |
attributes.commodity_type | string | null | Commodity this node was discovered for. |
attributes.country | string | null | Node country. |
attributes.relationship | string | null | Supply-ward role: operated-by / intermediary / first-mile. |
attributes.node_type | string | null | Node kind (mill, port, collection_centre, production_basin, …). |
attributes.latitude | number | null | Geocoded latitude (WGS84); null for region/unresolved nodes. |
attributes.longitude | number | null | Geocoded longitude (WGS84); null for region/unresolved nodes. |
attributes.geometry | object | null | Raw GeoJSON geometry (Point or Polygon), or null when unresolved. |
attributes.location_precision | string | How precisely the address or name resolved to coordinates: EXACT / LOCALITY (points) · DISTRICT / REGION / BASIN (polygons) · UNRESOLVED. Not a confidence that the site is there; use confidence_level and the imagery fields for that. |
attributes.geometry_kind | string | point / region / none. |
attributes.pin_status | string | null | The satellite check of the pin, distinct from confidence_level: verified (a street-address pin whose imagery shows the site) · not_verified (a street-address pin the imagery did not confirm, or did not check) · approximate (a town or area pin, not a site). null when the precision is unknown. |
attributes.pin_status_reason | string | null | Why the pin is not verified, in words a customer can read, e.g. "town only: needs a street address" or "the pin has not been checked". null when pin_status is verified. |
attributes.documented | boolean | True when tied to a cited source that was verified against the grounding results. |
attributes.linkage_type | string | null | deterministic (one of the node's own citations is a valid linked source: see sources[].links) · inferred (a link was proposed, by the name, the domain, a citation or the model, but no valid linked source states it) · probabilistic (inferred from the sourcing region). |
attributes.tie_basis | string | null | What ties the node to the company: named_together · trade_flow · certification · corporate · region_only. For a deterministic node, the tie is backed by proof; otherwise it is a proposed tie. region_only means that only the commodity and region connect them. null for a task that predates the field. |
attributes.stable_core | boolean | True for the reproducible core: a specific, located, evidence-backed facility (vs the fresher single-pass tail). |
attributes.corroboration_count | number | How many independent discovery passes surfaced this node. |
attributes.match_confidence | number | null | Match confidence (0..1); see the interpretation guidance below. |
attributes.confidence_level | "low" | "medium" | "high" | null | Tier from match_confidence: high at 0.70 or more, medium at 0.45 or more, otherwise low. |
attributes.imagery_confidence_score | number | null, optional | Satellite-imagery confidence (0..1) that the point shows the facility. See the imagery note below. |
attributes.imagery_confidence_comment | string | null, optional | One sentence that explains imagery_confidence_score. |
attributes.supply_chain_role | string | null, optional | Supply-chain role: first_mile · downstream · unknown. Derived from intake material and node classification, independently of whether imagery returned. The ingest gate also considers classification and raw/processed intake. |
attributes.anchor_offset_m | number | null, optional | Metres the imagery check moved the point to a better facility match. null when it did not move the point. |
attributes.confidence_reasoning | string | null | Why the model assigned its confidence. |
attributes.evidence_summary | string | null | Short evidence digest backing the node. |
attributes.link_to_company | string | null | How the node connects toward the company's first mile. |
attributes.link_basis | string | null | What proposed the link: name (the company's name on the site) · registry (a registry or dataset record) · domain (the company's own domain) · citation (a retrieved source) · unconfirmed_row (an earlier sweep's unvetted registry row) · model (the model's own claim with nothing else behind it). Kept when the link is not accepted. null when no link was proposed. Absent for a task that predates the field. |
attributes.link_verified | boolean | True when one of the node's own citations is a valid linked source. Only then is linkage_type deterministic; a proposed link without one publishes as inferred. Absent for a task that predates the field. |
attributes.sources | array | Grounding citations: { title, url, verified }, plus these when known: record_id (the dataset's own id: a certificate number, asset id or LEI), record_url (a page for that one record; url stays the dataset's landing page), evidence_text (up to 300 characters: the matched record fields, the page's own words around the node for a linked web source, or the credited web prose for any other), attribution (span or none; none means no prose credited the web source, so verified rests on the title match alone), pooled (true when the citation was found on another row for the same entity) and links (true for a valid linked source: the registry record tying the entity to the company, a dataset record whose holder names the company, or a web source whose fetched page names the node and the company). |
attributes.discovery_depth | number, optional | Tier of the supply graph the node was found at. 1 = found by the root sweep, 2 = by a sweep of a depth-1 node, and so on. Traversal only. |
attributes.parent_entity | string | null, optional | Company whose sweep found the node: the searched company on a depth-1 node, else the parent supplier. null only when the search had no company name. Traversal only. |
attributes.discovery_lineage | string[], optional | Companies from the searched company down to the node's parent, both included: [company] on a depth-1 node. Traversal only. |
attributes.relation | string | null, optional | The link to the company: supplies · manages · own_site · same_group · co_listed. Only the first three can be deterministic. |
attributes.link_checks | object, optional | { source_located, both_parties_in_passage, relation_supported, fetch }, each true, false or null (the check could not run). |
attributes.link_failed_check | string | null, optional | The first failed check, or null when all passed. |
attributes.resolved_role | string | null, optional | The one supply-chain role resolved from node type, relation and the model's tag. |
attributes.role_conflict | boolean, optional | True when relationship and supply_chain_role disagreed. |
attributes.shared_coordinate | boolean, optional | True when other distinct nodes share this coordinate, so the point is a centroid. |
attributes.imagery_check | string | null, optional | facility · forest · none: which plausibility check scored the node. |
attributes.forest_confidence_score | number | null, optional | Forest plausibility (0..1) for a plot or plantation node. |
attributes.provisional | boolean, optional | True on a candidate from a running search. Review only; never ingested. |
attributes.generation | number, optional | Snapshot generation in which the candidate last changed. |
attributes.ingestable | boolean | null, optional | Whether the ingest gate would stage this candidate under the requested linkage/confidence filters: by default, a first-mile or aggregation site, deterministic links on every hop, an EXACT point and confidence that is not low. A missing tier is accepted, even with an explicit confidence floor; ingestability does not prove medium/high confidence. Explicit ingestion filters can change the verdict. |
attributes.ingest_block_reason | string | null, optional | Why the ingest gate under the requested filters would not stage this candidate, worded as the ingest rejection detail, e.g. "approximate location (town only): needs a street address". null when ingestable is true. An explicit linkage, location_precision or min_confidence filter on ingest can change it. |
attributes.to_ingest | string | null, optional | The one thing that would make this candidate ingestable, as the ingest rejection to_ingest reports it, e.g. "confirm the supplier relationship" or "provide the site's street address". A deeper node refused on its path names the companies above it whose link is not confirmed. null when ingestable is true, and when nothing would: a port, an office, or a site that takes processed input. |
Each sources[] entry can also carry fetch_status (read / unreadable),
fetch_error, resolved_url, passage (the located passage that names both
parties), passage_locator, party_matches ({ party, on, value, strength }),
relation, relation_basis and model_reasoning (the model's own note, not
text found in the document).
Imagery fields: absent and null are different. The imagery fields are
imagery_confidence_score, imagery_confidence_comment and
anchor_offset_m. They are absent when the check did not return and null
when it returned without a value. Neither case is a failed imagery verdict.
supply_chain_role is a separate classification field.
▶Interpreting match confidence
Review confidence alongside precision, linkage evidence and imagery comments.
Confidence alone does not determine ingestion eligibility: inferred or
probabilistic links can fail default criteria. Review ingestable, its
reasons and supporting evidence before upload.
▶Choosing candidates
This is conservative guidance for compliance work, not an extra API gate.
| Candidate | Suggested next step |
|---|---|
| Deterministic link, EXACT pin and imagery at or above the pass mark | Review the server's ingestability verdict and evidence before upload. A downstream processor or broken lineage can still fail. |
| Town-only, missing or unverified pin | Obtain a street address and validate it; do not treat it as a plot. |
| Inferred or probabilistic link | Confirm the supplier relationship before compliance use. Exploratory screening can explicitly widen the linkage filter; keep the uncertainty visible. |
| Imagery below the pass mark | Investigate the pin and facility identity before carrying it forward. |
Use 0.40 for timber within 23.5 degrees of the equator, otherwise 0.45. Supplier confirmation, imagery and a confidence tier describe different evidence; none alone establishes compliance.
▶Checked streaming
With partial=true, a running response contains candidates whose own
location checks have finished, plus meta.progress. It can initially
contain no candidates while the first checks run. A published pin stays
fixed, but evidence can grow and final selection can remove a candidate.
Each running candidate carries selection: pending or over_limit.
Keep generation deltas and meta.removed_ids in sync; the final result
also lists streamed ids it dropped. A pin demoted after publication can
retain its coordinates with pin_retained: true, while pin_status
becomes approximate. Coordinates alone do not make it ingestable.
Running tasks cannot be ingested; wait for the final result.
▶Response schema — meta
meta| Field | Type | Description |
|---|---|---|
company | string | Echo of the requested company. |
commodities | string[] | Commodities mapped (resolved or inferred). |
commodities_inferred | boolean | True when commodities were inferred (none supplied). |
countries | string[] | Country scope (supplied, or grounded on a global request). |
countries_inferred | boolean | True when the country scope was grounded (none supplied). |
scope | string | country or global. |
relationship | string | Relationship filter applied. |
total_candidates | number | Number of locations returned. |
precision_breakdown | object | Count of returned nodes by precision tier. |
dropped_weak_grounding | number | Candidates suppressed for thin evidence (total). |
dropped_no_evidence | number | Suppressed: no verified source / connector hit / corroboration. |
dropped_not_stable_core | number | Suppressed: had evidence but not a specific, located facility. |
grounded_passes_total | number | Total grounded discovery passes run. |
grounded_passes_failed | number | Passes that errored (transient) after retries. |
degraded | boolean | True when some passes failed — coverage is partial; retry. |
warning | string | Set when the search was too wide to run or no commodity resolved. |
narrow_required | boolean | True when nothing was searched because the commodities x countries were over the limit. Search again with fewer countries or a narrower product. |
completeness | object | Best-effort LLM coverage estimate: { overview, percent, description }. |
traversal | object, optional | How a supply-graph traversal went. Present only when the task was dispatched with traverse: true. See below. |
▶Response schema — meta.traversal
meta.traversalA traversal also sets meta.degraded to true when any branch failed.
| Field | Type | Description |
|---|---|---|
sweeps | number | Paid sweeps run, the root sweep included. |
depth_reached | number | Deepest tier a returned node sits at. |
max_depth | number | Depth circuit breaker in force. |
max_sweeps | number | null | Sweep budget in force. null = no budget. |
max_children_per_sweep | number | null | Per-parent fan-out cap. null = no cap. |
child_limit | number | Candidate limit on each child sweep. |
branches_ended | object | Count of branches by why they ended: first_mile, visited, no_new_entities, too_wide (the supplier's own search was over the combination limit, so it was not run). |
failed_branches | string[] | Suppliers whose child sweep failed. Their upstream is unexplored, not empty. |
too_wide_branches | string[] | Suppliers whose own search was over the combination limit, so it was not run. Their upstream is unexplored, not empty. |
circuit_breaker_tripped | boolean | True when a branch reached max_depth. |
defect | string, optional | max_depth_reached when the circuit breaker tripped. Absent on a clean run. |
unexpanded_at_max_depth | string[] | Intermediaries the depth breaker left unexpanded. |
unexpanded_at_max_sweeps | string[] | Intermediaries left unexpanded when the sweep budget ran out. |
unexpanded_over_child_cap | string[] | Intermediaries cut by max_children_per_sweep. |
An intermediary in any unexpanded_* list, failed_branches or too_wide_branches, is a
supply-chain gap. The graph is not complete there.
Required scope:
geocode:read