List Artifacts

List artifacts visible to your organization.

Returns a paginated list of artifacts visible to your organization, newest first. Use this to find the most recent completed artifact, audit failures, or build a catalogue UI. See the Artifacts overview for the lifecycle and bundle structure.

Use cases

  • Find the most recent completed artifact for an org without tracking IDs externally.
  • Audit failed artifacts and read error_code / error_message for triage.
  • Filter by created_at to retrieve artifacts from a specific time window for compliance reporting.
  • Find the artifact(s) generated for a given scope โ€” e.g. filter[assets.task_id]=eq:<upload id> to locate the artifact an ingestion fast-path (create_artifact: true) produced.

Filters

Use filter[field]=condition:value syntax. See query-parameters.md for the full filter grammar.

FilterTypeAllowed conditionsDescription
filter[status]enumeq, inqueued, processing, succeeded, failed, cancelled, purged. Filter on purged to list everything that has aged out of retention. See the Artifacts overview for the succeeded/completed naming convention.
filter[type]enumeq, inrelational_full.
filter[format]enumeq, ingeoparquet.
filter[created_at]dateeq, gt, gte, lt, lteISO-8601 timestamp. in is not supported on date filters; use a range comparison instead.

Scope filters

You can also list the artifact(s) generated for a specific scope. Each accepts a single eq value and mirrors the create-time scope model (see the Artifacts overview):

FilterTypeAllowed conditionsDescription
filter[assets.task_id] (alias filter[asset_task_id])uuideqArtifacts scoped to one ingestion/upload. Use this to find the artifact an ingestion fast-path (create_artifact: true) produced.
filter[facility_id]stringeqArtifacts scoped to one facility.
filter[location_id]stringeqArtifacts scoped to one facility / shed / plot public id.
filter[supplier_id]uuideqArtifacts scoped to one supplier.
filter[name]stringeqArtifacts scoped by location normalised name.

Pagination

Standard page + page_size paging. The envelope's meta.total and meta.has_next drive UI cursors. See query-parameters.md for pagination conventions.

Response schema (data[])

FieldTypeDescription
type"artifact"Always "artifact".
iduuidArtifact ID.
links.selfstringURL of this artifact.

attributes

FieldTypeDescription
organization_iduuidOwning organization.
typeenumrelational_full.
formatenumgeoparquet.
statusenumqueued | processing | succeeded | failed | cancelled | purged.
error_codestring | nullStable, machine-readable failure code (e.g. artifact_too_large, internal_error). null unless status: "failed". Match on this rather than error_message.
error_messagestring | nullHuman-readable failure summary, derived from error_code. Populated when status: "failed". Deliberately generic โ€” the raw exception text is never exposed.
storage_objectsarrayOne entry per file in the bundle. Paths are relative identifiers, not URLs โ€” mint a signed URL to download.
partitioningobject | nullnull for unpartitioned bundles (the only shape today).
size_bytesint | nullTotal bytes across storage_objects. Populated on terminal success.
sha256string | nullDeterministic catalogue hash across all storage_objects. Populated on terminal success.
row_countsobject | nullPer-table row counts. Shape is artifact-type specific. Populated on terminal success.
created_atISO 8601Row creation timestamp.
updated_atISO 8601 | nullMost recent status change.
started_atISO 8601 | nullWhen the generation task began.
completed_atISO 8601 | nullTerminal timestamp (success, failure, or cancellation).
purged_atISO 8601 | nullWhen retention deleted the artifact's files and the record became a tombstone. null unless status: "purged".
download_linksobjectPer-artifact tally of persistent download links: { active, expired, revoked, purged }. Mutually exclusive, and they sum to every link ever minted for the artifact. Each link counts under the first thing that ended its life (purged โ†’ revoked โ†’ expired โ†’ active). An artifact is only ever aged out while active is 0.
action_requiredenum | nullregenerate on a purged artifact โ€” request a new one with the same filters. null otherwise.

storage_objects[]

FieldTypeDescription
relative_pathstringStable file identifier within the artifact. Not a URL โ€” pass to Mint Signed URLs to download.
size_bytesintFile size in bytes.
sha256stringSHA-256 of the file contents.

Status codes

  • 200 โ€” Success.
  • 400 โ€” Invalid filter / query parameters.
  • 401 โ€” Missing or invalid API key.
  • 403 โ€” Caller lacks the artifacts:read scope.

Required scope: artifacts:read