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
completedartifact for an org without tracking IDs externally. - Audit
failedartifacts and readerror_code/error_messagefor triage. - Filter by
created_atto 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.
| Filter | Type | Allowed conditions | Description |
|---|---|---|---|
filter[status] | enum | eq, in | queued, 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] | enum | eq, in | relational_full. |
filter[format] | enum | eq, in | geoparquet. |
filter[created_at] | date | eq, gt, gte, lt, lte | ISO-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):
| Filter | Type | Allowed conditions | Description |
|---|---|---|---|
filter[assets.task_id] (alias filter[asset_task_id]) | uuid | eq | Artifacts scoped to one ingestion/upload. Use this to find the artifact an ingestion fast-path (create_artifact: true) produced. |
filter[facility_id] | string | eq | Artifacts scoped to one facility. |
filter[location_id] | string | eq | Artifacts scoped to one facility / shed / plot public id. |
filter[supplier_id] | uuid | eq | Artifacts scoped to one supplier. |
filter[name] | string | eq | Artifacts 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[])
data[])| Field | Type | Description |
|---|---|---|
type | "artifact" | Always "artifact". |
id | uuid | Artifact ID. |
links.self | string | URL of this artifact. |
โถattributes
attributes| Field | Type | Description |
|---|---|---|
organization_id | uuid | Owning organization. |
type | enum | relational_full. |
format | enum | geoparquet. |
status | enum | queued | processing | succeeded | failed | cancelled | purged. |
error_code | string | null | Stable, machine-readable failure code (e.g. artifact_too_large, internal_error). null unless status: "failed". Match on this rather than error_message. |
error_message | string | null | Human-readable failure summary, derived from error_code. Populated when status: "failed". Deliberately generic โ the raw exception text is never exposed. |
storage_objects | array | One entry per file in the bundle. Paths are relative identifiers, not URLs โ mint a signed URL to download. |
partitioning | object | null | null for unpartitioned bundles (the only shape today). |
size_bytes | int | null | Total bytes across storage_objects. Populated on terminal success. |
sha256 | string | null | Deterministic catalogue hash across all storage_objects. Populated on terminal success. |
row_counts | object | null | Per-table row counts. Shape is artifact-type specific. Populated on terminal success. |
created_at | ISO 8601 | Row creation timestamp. |
updated_at | ISO 8601 | null | Most recent status change. |
started_at | ISO 8601 | null | When the generation task began. |
completed_at | ISO 8601 | null | Terminal timestamp (success, failure, or cancellation). |
purged_at | ISO 8601 | null | When retention deleted the artifact's files and the record became a tombstone. null unless status: "purged". |
download_links | object | Per-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_required | enum | null | regenerate on a purged artifact โ request a new one with the same filters. null otherwise. |
โถstorage_objects[]
storage_objects[]| Field | Type | Description |
|---|---|---|
relative_path | string | Stable file identifier within the artifact. Not a URL โ pass to Mint Signed URLs to download. |
size_bytes | int | File size in bytes. |
sha256 | string | SHA-256 of the file contents. |
โถStatus codes
200โ Success.400โ Invalid filter / query parameters.401โ Missing or invalid API key.403โ Caller lacks theartifacts:readscope.
Required scope:
artifacts:read