Artifacts

Reach for an artifact when you want all of the data, once, rather than a live query against a single entity:

• BI / data-warehouse handoff — pull a self-describing relational snapshot into DuckDB, GeoPandas, BigQuery, or Snowflake. One file, all entities, no join orchestration against the API.
• Regulatory submissions — a deterministic, hash-stamped (sha256) bundle tied to a specific filter window makes a defensible due-diligence pack. The embedded manifest records lineage and model versions, so the export documents itself.
• A snapshot for a moment in time — assessments evolve as new imagery and model runs land. An artifact freezes the data as it stood when generated, so you can reference exactly what was true at submission time.
• Dashboard handoff — a short-lived signed-URL response carries a links.dashboard_url deep link that opens the artifact directly in Epoch's dashboard.
• Sharing with a person — request a lifetime beyond 7 days and you get a durable, revocable download link that still works weeks later. See short-lived vs. long-lived links.
• Event-driven pipelines — subscribe to artifact.completed / artifact.failed webhooks and kick off downstream processing the moment a bundle is ready.

If you only need a few live records, query the Locations or Metrics endpoints directly — artifacts are for the bulk, frozen-snapshot case.

An artifact can be requested on demand at any time, or created automatically at ingestion as part of an upload.

Both paths produce the same kind of artifact resource and walk the same lifecycle — they differ only in what triggers generation and how the scope is set.

// POST /ingestions/assets  (multipart, or the signed-URL JSON variant)
{
  "create_artifact": true,
}

Artifacts are asynchronous regardless of how they're created. The status field walks one of these paths:

queued → processing → completed → purged
                   → failed
                   → cancelled

• queued — accepted, waiting to start.
• processing — being generated.
• completed — terminal success. storage_objects, size_bytes, sha256, and row_counts are populated; signed URLs can now be minted.
• failed — terminal failure. The response carries a safe error_message and an error_code (e.g. artifact_too_large). On-demand requests can retry with the same idempotencyKey.
• cancelled — terminal, caller-initiated via DELETE /artifacts/:id; only valid from a non-terminal state.
• purged — the files aged out. The record survives as a tombstone: purged_at says when, action_required says regenerate, and the file metadata still describes what the export held. Downloads no longer resolve. See Retention.

API field vs. prose name. In raw API responses the success state is literally "status": "succeeded". Webhook payloads (artifact.completed) and this documentation say "completed". They are the same terminal state — filter on succeeded, subscribe on completed. See task-and-entity-statuses.md.

Artifacts are generated exports, not a system of record — they don't live forever.

• failed / cancelled artifacts are removed 7 days after they reach that state. Both the record and any partial output are deleted, so a GET /artifacts/:id for one of them returns 404 afterwards. Read the error_code while it's there; if you need the export, re-request it.
• completed artifacts age out 180 days after they complete. The files are deleted and the status becomes purged. You are never left guessing: the record stays for a further 90 days carrying purged_at, action_required: "regenerate", and the original file metadata. After that the record goes too and the id returns 404.
• A live download link keeps an artifact alive. Retention will not delete the files behind a link that is still in date and not revoked, however old the artifact is — so a link you handed someone works for its full TTL. The clock effectively restarts each time you mint a fresh link. The 180-day window can never be shorter than the maximum link TTL.
• A dead download link is purged 3 days after it dies. A link dies when you revoke it, or when it passes expires_at. Three days later the stored credential is destroyed and the link moves into the purged count. The entry stays in GET /artifacts/:id/signed-urls reporting status: purged with action_required: remint. A purged link no longer keeps its artifact alive.

Read download_links on the artifact to see why one aged out. The four counts (active, expired, revoked, purged) are mutually exclusive and sum to every link you ever minted for it, and a purged artifact always shows active: 0. Each link is counted under the first thing that ended its life — purged, then revoked, then expired, then active — so a link you revoked stays in revoked even after its expiry passes.

{
  "status": "purged",
  "purged_at": "2026-07-01T10:00:00.000Z",
  "action_required": "regenerate",
  "download_links": { "active": 0, "expired": 1, "revoked": 1, "purged": 2 }
}

To find everything that has aged out, filter the list: GET /v1/artifacts?filter[status]=eq:purged.

If you need a bundle to outlive the artifact record, download it and keep the file.

Every artifact is one GeoParquet file holding rows from many logical tables, distinguished by a table_name discriminator column:

A self-describing manifest is embedded in the file's metadata — data lineage, model versions, per-table keys and column descriptions, and usage constraints — so the export can be understood without further API calls. Geometry is OGC WKB in OGC:CRS84 (longitude, latitude). See the Artifacts endpoint docs for the manifest layout and DuckDB / GeoPandas / QGIS consuming recipes.

A completed artifact isn't downloadable until you ask for a URL. How long you ask for decides what you get — there's no separate endpoint, just the requested lifetime on POST /artifacts/:id/signed-urls.

Seven days is the ceiling for a directly-signed URL, so anything longer is served by a different mechanism: Epoch issues a durable link that re-signs a fresh short-lived URL behind the scenes on each hit. The link keeps working for its whole lifetime without you re-minting.

Reach for a short-lived URL when a machine consumes the bundle straight away — a pipeline step, a DuckDB query, a one-shot load. Reach for a persistent link when a person is the recipient and may not act on it today: an auditor working through a submission, a customer contact, a colleague who'll open it next week. A seven-day URL handed to a human is usually dead by the time they click it.

Artifacts are strictly scoped to your organization. A parent-org caller sees their own artifacts plus those of direct child orgs; the x-acting-as header narrows a request to a single child. Download URLs are never embedded in webhook payloads or in read responses — you mint them explicitly, and minting requires its own artifacts:sign scope, separate from artifacts:write. See scopes.md.

• Artifacts endpoint reference — request bodies, full filter model, manifest, signed URLs, consuming recipes.
• Asset Upload — the ingestion flow the fast-path hooks into.
• Webhooks — artifact.completed / artifact.failed delivery and HMAC verification.
• Assessments Overview — what the assessment slices in the bundle mean.