Get Source Discovery Status

Poll the status of an async source-discovery task started by POST /discovery/source. Poll until status is completed (then fetch GET /discovery/source/{taskId}/results) or failed.

A one-tier sweep normally completes in a few minutes. A traversal (traverse: true) runs for hours: about 15 minutes per round of sweeps. Poll a traversal about every 15 minutes.

Request

Method & Path

GET /discovery/source/{taskId}/status

Path parameters

  • taskId (UUID, required) โ€” the discovery task id returned by the dispatch call. A non-UUID value is rejected with 400.

Headers

  • x-api-key โ€” required.
  • Accept: application/json

Response

  • 200 โ€” a source_discovery_task resource with the normalised lifecycle status and an error message (set only when failed).
  • 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 it belongs to a different organization (ownership is enforced upstream and returns 404 โ€” never 403 โ€” so a guessed id cannot be probed).
  • 502 โ€” a transient upstream failure fetching the status. Safe to retry.

Response schema

FieldTypeDescription
typestringAlways source_discovery_task.
idstringThe discovery task id.
attributes.status"pending" | "processing" | "completed" | "failed"Normalised lifecycle status. completed is reported only once the discovery sub-task has written its result blob, so a completed status is always safe to fetch results from.
attributes.errorstring | nullFailure message; null unless status is failed.
attributes.partial_readybooleantrue when a provisional snapshot of the running search can be fetched with โ€ฆ/results?partial=true.
attributes.generationnumberRises with each snapshot; 0 when none has been published. Pass the last one read as since_generation.
attributes.provisional_countnumber | nullCandidates in the newest snapshot. null when the discovery service did not report it.
attributes.traverseboolean, optionaltrue when the task is a supply-graph traversal. Poll it about every 15 minutes. Absent when the discovery service did not report it.
links.resultsstringURL to fetch the discovered locations.

Required scope: geocode:read