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 with 400.

Query parameters

  • linkage (string[], optional) and min_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 a 409. meta.partial is then true, and each candidate carries provisional and generation.
  • since_generation (integer ≥ 0, optional) — with partial=true, return only the candidates that changed after this snapshot generation. meta.candidate_ids lists 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_location resources, with discovery metadata on meta. An empty data array with a meta.warning means no commodity could be resolved/inferred or nothing cleared the evidence bar.
  • 400 — taskId is 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)

FieldTypeDescription
typestringAlways source_location.
idstring | nullStable candidate id used for decisions and ingestion; null for a legacy blob without ids (re-run discovery).
attributes.namestringDisplay name (node name, else address/company).
attributes.supplier_namestring | nullDiscovered node/operator name; null when undocumented.
attributes.addressstring | nullLocality, admin area, country.
attributes.commodity_typestring | nullCommodity this node was discovered for.
attributes.countrystring | nullNode country.
attributes.relationshipstring | nullSupply-ward role: operated-by / intermediary / first-mile.
attributes.node_typestring | nullNode kind (mill, port, collection_centre, production_basin, …).
attributes.latitudenumber | nullGeocoded latitude (WGS84); null for region/unresolved nodes.
attributes.longitudenumber | nullGeocoded longitude (WGS84); null for region/unresolved nodes.
attributes.geometryobject | nullRaw GeoJSON geometry (Point or Polygon), or null when unresolved.
attributes.location_precisionstringHow 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_kindstringpoint / region / none.
attributes.pin_statusstring | nullThe 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_reasonstring | nullWhy 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.documentedbooleanTrue when tied to a cited source that was verified against the grounding results.
attributes.linkage_typestring | nulldeterministic (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_basisstring | nullWhat 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_corebooleanTrue for the reproducible core: a specific, located, evidence-backed facility (vs the fresher single-pass tail).
attributes.corroboration_countnumberHow many independent discovery passes surfaced this node.
attributes.match_confidencenumber | nullMatch confidence (0..1); see the interpretation guidance below.
attributes.confidence_level"low" | "medium" | "high" | nullTier from match_confidence: high at 0.70 or more, medium at 0.45 or more, otherwise low.
attributes.imagery_confidence_scorenumber | null, optionalSatellite-imagery confidence (0..1) that the point shows the facility. See the imagery note below.
attributes.imagery_confidence_commentstring | null, optionalOne sentence that explains imagery_confidence_score.
attributes.supply_chain_rolestring | null, optionalSupply-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_mnumber | null, optionalMetres the imagery check moved the point to a better facility match. null when it did not move the point.
attributes.confidence_reasoningstring | nullWhy the model assigned its confidence.
attributes.evidence_summarystring | nullShort evidence digest backing the node.
attributes.link_to_companystring | nullHow the node connects toward the company's first mile.
attributes.link_basisstring | nullWhat 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_verifiedbooleanTrue 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.sourcesarrayGrounding 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_depthnumber, optionalTier 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_entitystring | null, optionalCompany 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_lineagestring[], optionalCompanies from the searched company down to the node's parent, both included: [company] on a depth-1 node. Traversal only.
attributes.relationstring | null, optionalThe link to the company: supplies · manages · own_site · same_group · co_listed. Only the first three can be deterministic.
attributes.link_checksobject, optional{ source_located, both_parties_in_passage, relation_supported, fetch }, each true, false or null (the check could not run).
attributes.link_failed_checkstring | null, optionalThe first failed check, or null when all passed.
attributes.resolved_rolestring | null, optionalThe one supply-chain role resolved from node type, relation and the model's tag.
attributes.role_conflictboolean, optionalTrue when relationship and supply_chain_role disagreed.
attributes.shared_coordinateboolean, optionalTrue when other distinct nodes share this coordinate, so the point is a centroid.
attributes.imagery_checkstring | null, optionalfacility · forest · none: which plausibility check scored the node.
attributes.forest_confidence_scorenumber | null, optionalForest plausibility (0..1) for a plot or plantation node.
attributes.provisionalboolean, optionalTrue on a candidate from a running search. Review only; never ingested.
attributes.generationnumber, optionalSnapshot generation in which the candidate last changed.
attributes.ingestableboolean | null, optionalWhether 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_reasonstring | null, optionalWhy 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_ingeststring | null, optionalThe 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.

CandidateSuggested next step
Deterministic link, EXACT pin and imagery at or above the pass markReview the server's ingestability verdict and evidence before upload. A downstream processor or broken lineage can still fail.
Town-only, missing or unverified pinObtain a street address and validate it; do not treat it as a plot.
Inferred or probabilistic linkConfirm the supplier relationship before compliance use. Exploratory screening can explicitly widen the linkage filter; keep the uncertainty visible.
Imagery below the pass markInvestigate 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

FieldTypeDescription
companystringEcho of the requested company.
commoditiesstring[]Commodities mapped (resolved or inferred).
commodities_inferredbooleanTrue when commodities were inferred (none supplied).
countriesstring[]Country scope (supplied, or grounded on a global request).
countries_inferredbooleanTrue when the country scope was grounded (none supplied).
scopestringcountry or global.
relationshipstringRelationship filter applied.
total_candidatesnumberNumber of locations returned.
precision_breakdownobjectCount of returned nodes by precision tier.
dropped_weak_groundingnumberCandidates suppressed for thin evidence (total).
dropped_no_evidencenumberSuppressed: no verified source / connector hit / corroboration.
dropped_not_stable_corenumberSuppressed: had evidence but not a specific, located facility.
grounded_passes_totalnumberTotal grounded discovery passes run.
grounded_passes_failednumberPasses that errored (transient) after retries.
degradedbooleanTrue when some passes failed — coverage is partial; retry.
warningstringSet when the search was too wide to run or no commodity resolved.
narrow_requiredbooleanTrue when nothing was searched because the commodities x countries were over the limit. Search again with fewer countries or a narrower product.
completenessobjectBest-effort LLM coverage estimate: { overview, percent, description }.
traversalobject, optionalHow a supply-graph traversal went. Present only when the task was dispatched with traverse: true. See below.

Response schema — meta.traversal

A traversal also sets meta.degraded to true when any branch failed.

FieldTypeDescription
sweepsnumberPaid sweeps run, the root sweep included.
depth_reachednumberDeepest tier a returned node sits at.
max_depthnumberDepth circuit breaker in force.
max_sweepsnumber | nullSweep budget in force. null = no budget.
max_children_per_sweepnumber | nullPer-parent fan-out cap. null = no cap.
child_limitnumberCandidate limit on each child sweep.
branches_endedobjectCount 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_branchesstring[]Suppliers whose child sweep failed. Their upstream is unexplored, not empty.
too_wide_branchesstring[]Suppliers whose own search was over the combination limit, so it was not run. Their upstream is unexplored, not empty.
circuit_breaker_trippedbooleanTrue when a branch reached max_depth.
defectstring, optionalmax_depth_reached when the circuit breaker tripped. Absent on a clean run.
unexpanded_at_max_depthstring[]Intermediaries the depth breaker left unexpanded.
unexpanded_at_max_sweepsstring[]Intermediaries left unexpanded when the sweep budget ran out.
unexpanded_over_child_capstring[]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