Get Artifact

Fetch a single artifact by ID.

Poll this endpoint while an artifact is queued or processing. Once status reaches succeeded, mint signed download URLs via POST /artifacts/:id/signed-urls. See the Artifacts overview for the full lifecycle and the succeeded/completed naming convention.

Use cases

Poll the artifact's status after a 202 from POST /artifacts. Use the retryAfterSeconds hint from the create response as a polling cadence.
Inspect row_counts, size_bytes, and sha256 after the artifact completes — handy for audit logs or to drive a UI summary.
Read error_message after a failed artifact for triage.

Path parameters

Param	Type	Description
`id`	uuid	Artifact ID. Must be visible to your organization.

Response schema (`data`)

Field	Type	Description
`type`	`"artifact"`	Always `"artifact"`.
`id`	uuid	Artifact ID.
`links.self`	string	URL of this artifact.

`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	Empty until the artifact reaches `completed`. See `storage_objects[]` below.
`partitioning`	object \| null	`null` for unpartitioned bundles.
`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 (e.g. `{ "locations": 142, "plots": 138 }`). 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. Null while `queued`.
`completed_at`	ISO 8601 \| null	Terminal timestamp — set on `succeeded`, `failed`, or `cancelled`.
`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), so a revoked link stays in `revoked` after its expiry passes. 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. Failed artifacts are not flagged here; retry those under the same `Idempotency-Key`.

`storage_objects[]`

Field	Type	Description
`relative_path`	string	Stable file identifier within the artifact. Not a URL — pass the artifact's `id` to Mint Signed URLs to obtain a downloadable URL.
`size_bytes`	int	File size in bytes.
`sha256`	string	SHA-256 of the file contents.

`partitioning`

Reserved for hive-partitioned artifacts; always null today. When populated:

Field	Type	Description
`scheme`	string	Partitioning scheme (e.g. `"hive"`).
`keys`	string[]	Ordered partition key names.

Status codes

200 — Success.
400 — Invalid id (not a UUID).
401 — Missing or invalid API key.
403 — Caller lacks the artifacts:read scope.
404 — Artifact does not exist or is not visible to your organization. The two cases return the same response so an out-of-scope ID cannot be used to discover other orgs' artifact IDs.

Required scope: artifacts:read