Status and timestamps
How to tell from the API whether a build for a resource's current configuration has finished, and whether it worked.
Faraday builds each resource in the background: it reads the resource's configuration and inputs, does the work, and writes the output. When you change a resource, the next build uses the change. Three build timestamps on every resource (last_updated_config_at, last_read_input_at, and last_updated_output_at) tell you whether a build with your current configuration has finished, or whether status still describes an earlier build or one in flight. Read them together with status; neither is enough alone.
The fields
| Field | What it records |
|---|---|
last_updated_config_at | When Faraday registered the latest change to the resource's configuration, or the latest force_update. Omitted on some Faraday-managed streams and traits. |
last_read_input_at | When the latest finished build started reading the resource's configuration and inputs. Omitted until a build finishes (whether ready or error). |
last_updated_output_at | When a successful build last changed the resource's output. Omitted until a build writes output; a build that finds nothing new to write leaves it alone. |
status | The state of the latest build: new (never built), starting, running, ready, or error. |
status_changed_at | When status last changed. Use it to bound how long you wait on an in-flight build or an error. |
status_error | The error message, when status is error. |
status_needs_fix_from | What Faraday is waiting for before it builds a resource in error again: user, support, or omitted for nothing. |
While status_needs_fix_from is omitted and archived_at is unset, a resource builds again whenever last_updated_config_at is later than last_read_input_at, or when one of its direct upstream resources has a last_updated_output_at later than its own last_read_input_at. Some resources also rebuild on a schedule.
Has my current configuration built?
A build with the current configuration has finished once last_read_input_at is present and at or after last_updated_config_at (or once last_read_input_at is present when last_updated_config_at is omitted). Until then, no build with the latest change has finished: starting or running means a build is in progress, and ready or error right after an update is from the build before it. Every read of a resource carries these fields, so one GET tells you.
Once last_read_input_at has reached last_updated_config_at:
readymeans your configuration took effect.errormeans the build failed (seestatus_errorandstatus_needs_fix_from).startingorrunningmeans an earlier build with your configuration finished and a later build is now running. Because failed builds also advancelast_read_input_at, that earlier build succeeded iflast_updated_output_atis at or afterlast_read_input_at(a routine refresh is now running on top of live output). Otherwise the earlier build may have failed or written nothing new, so keep polling untilstatusisreadyorerror.
On each read, check that a build can still run: no build will start while archived_at is set, while status_needs_fix_from is user or support, or when the account is suspended or has deletion_scheduled_for set. Updating a resource's build configuration or calling force_update on it clears user before the response returns, though a build that was already in flight from before your update can still finish in error and set user or support afterward.
For example, right after an update a cohort reads:
{
"id": "2c1881c4-a0c0-424d-89e1-b481f3cb118c",
"last_updated_config_at": "2026-11-03T15:04:05.120Z",
"last_read_input_at": "2026-11-03T14:10:31.007Z",
"status": "ready"
}
ready here is the 14:10 build, which ran before your change. While the new build runs, status becomes starting and then running, and last_read_input_at stays 14:10:31.007Z. Once that build finishes, a read returns:
{
"id": "2c1881c4-a0c0-424d-89e1-b481f3cb118c",
"last_updated_config_at": "2026-11-03T15:04:05.120Z",
"last_read_input_at": "2026-11-03T15:04:09.452Z",
"status": "ready"
}
last_read_input_at has now moved past last_updated_config_at, so the build that started reading inputs at 15:04:09 included your change and succeeded.
In code, parse timestamps as instants (both last_read_input_at and last_updated_config_at are optional) rather than comparing raw strings:
class ResourceBuildReading {
readonly status: "new" | "starting" | "running" | "ready" | "error";
readonly statusNeedsFixFrom: "user" | "support" | null;
readonly lastUpdatedConfigAt: number | null;
readonly lastReadInputAt: number | null;
readonly lastUpdatedOutputAt: number | null;
readonly archivedAt: number | null;
constructor({ wire }: { wire: Record<string, unknown> }) {
this.status = wire.status as ResourceBuildReading["status"];
this.statusNeedsFixFrom =
(wire.status_needs_fix_from as "user" | "support" | undefined) ?? null;
this.lastUpdatedConfigAt =
typeof wire.last_updated_config_at === "string"
? Date.parse(wire.last_updated_config_at)
: null;
this.lastReadInputAt =
typeof wire.last_read_input_at === "string"
? Date.parse(wire.last_read_input_at)
: null;
this.lastUpdatedOutputAt =
typeof wire.last_updated_output_at === "string"
? Date.parse(wire.last_updated_output_at)
: null;
this.archivedAt =
typeof wire.archived_at === "string"
? Date.parse(wire.archived_at)
: null;
}
verdict({
waitForConfigAt,
}: {
waitForConfigAt: string | null;
}): "waiting" | "ready" | "error" | "archived" {
if (this.archivedAt !== null) return "archived";
if (this.status === "error" && this.statusNeedsFixFrom !== null) {
return "error";
}
const targetAt =
waitForConfigAt !== null
? Date.parse(waitForConfigAt)
: this.lastUpdatedConfigAt;
if (this.lastReadInputAt === null) return "waiting";
if (targetAt !== null && this.lastReadInputAt < targetAt) return "waiting";
if (this.status === "ready") return "ready";
if (this.status === "error") return "error";
if (
this.lastUpdatedOutputAt !== null &&
this.lastUpdatedOutputAt >= this.lastReadInputAt
) {
return "ready";
}
return "waiting";
}
}
Waiting for one particular change
If others may change the resource after you, comparing against the latest last_updated_config_at makes you wait for their changes too. To wait for yours alone, pass the last_updated_config_at that your create, update (POST /cohorts, PATCH /cohorts/{cohort_id}, and the like), or force_update response carried (waitForConfigAt above, or null to wait on the latest configuration). A POST /<resources>/{id}/force_update call returns:
{
"last_updated_config_at": "2026-11-03T15:04:05.120Z"
}
Two special cases:
- Display-only edits: An update that changes only display fields such as
nametriggers no build and returns the previouslast_updated_config_at, which a built resource'slast_read_input_athas already reached. - Hosted CSV uploads: Uploading or deleting a file at
/uploads/{directory}/{filename}registers a configuration change on every Hosted CSV dataset and atlas that readsdirectory. Re-read the dataset or atlas afterward if you need thelast_updated_config_atthat upload registered.
When a build fails
status_needs_fix_from says what has to happen before the resource builds again. It does not say whose fault the error is.
user: Faraday waits for you. Change the resource's build configuration or callforce_updateon it (changing onlyname, or updating an upstream resource, does not clearuser).support: Faraday waits for its support team.force_updateis refused with409 Conflict, and no build will pick up your changes or upstream updates until support acts.- Omitted: nothing blocks a rebuild. Faraday builds it again when an upstream resource produces new output or its schedule comes up. In an account where you own every upstream and no schedule runs soon, that trigger may never arrive; call
force_updateto retry immediately, or usestatus_changed_atto time out after your own patience window.
Upstream changes
A resource can be current with its own configuration and still behind its inputs. GET /graph returns one edge for each dependency in the account, with both ends' status and timestamps.
On an edge, a build of the downstream resource that read the upstream's latest output has finished once upstream_last_updated_output_at is present and downstream_last_read_input_at is at or after upstream_last_updated_output_at. Walking the edges from your inputs to your terminal resource and checking each node and edge follows a change through the whole pipeline.
Keep three graph rules in mind:
- Check every hop; do not compare endpoints directly. Faraday places managed
streamsandtraitsbetween adatasetand acohort. Also, if an intermediate resource rebuilds on new input and its own output does not change, itslast_updated_output_atstays put and Faraday skips rebuilding what sits below it. Checking each edge onGET /graphsees that the pipeline is caught up; comparing atarget'slast_read_input_atdirectly to adataset'slast_updated_output_atcan wait forever. - Stop on frozen downstream errors. If a downstream resource has
downstream_statusoferroranddownstream_status_needs_fix_fromofuserorsupport, Faraday will not rebuild it when an upstream produces new output. Treat that downstream as failed rather than waiting fordownstream_last_read_input_atto advance. GET /graphlists edges, not standalone resources. A resource with no upstream or downstream dependencies yet (such as a newconnection,place, or attribute-onlycohortbefore ascopeuses it) has no edges and is absent fromGET /graph. Read standalone resources withGET /<type>/{id}.
Polling and webhooks
Webhook endpoints receive resource.ready_with_update (when a build finishes ready and writes new output) and resource.errored. A build that finishes ready without changing output advances last_read_input_at, leaves last_updated_output_at alone, and sends no webhook. If you wait on a configuration change or force_update, keep a poll fallback alongside webhooks.
Back off between polls (for example from a few seconds up to 15 to 30 seconds). Preview datasets and cohorts often finish in seconds, while outcomes, persona sets, and large deliveries can run for tens of minutes.
Fields not to use for status
created_at is when the resource was created. updated_at is when its row last changed, which happens on your edits and also while Faraday builds it. last_updated_output_at alone cannot tell you whether a configuration change has built, because a build with unchanged output leaves it alone. Use last_updated_config_at and last_read_input_at.