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. Four timestamps on every resource 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. |
last_read_input_at | When the latest finished build started reading the resource's configuration and inputs. Omitted until a build finishes. |
last_updated_output_at | When a build last changed the resource's 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. |
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. |
A resource builds again whenever last_updated_config_at is later than last_read_input_at, or when one of its 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 at or after last_updated_config_at. Until then, no build with the latest change has finished: starting or running means one is in progress, and ready or error right after an update is from the build before it. Every read of a resource carries both timestamps, so one GET tells you.
Once last_read_input_at is at or after last_updated_config_at, ready means your configuration took effect, error means the build failed (see status_error and status_needs_fix_from), and starting or running means an earlier build already applied your configuration and a later refresh is now running on top of it.
Before waiting, check that a build can run: no build will start while archived_at is set, while status_needs_fix_from is support, or when the account's deletion_scheduled_for is set.
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.
Waiting for one particular change
If others may change the resource after you, the rule above makes you wait for their changes too. To wait for yours alone, compare last_read_input_at with the last_updated_config_at that your create or update (POST /cohorts, PATCH /cohorts/{cohort_id} and the like) or force_update response carried, instead of the one on the latest read.
An update that changes only display fields such as name triggers no build and returns the previous last_updated_config_at, which a built resource's last_read_input_at has already reached.
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_update(changing onlynamedoes not trigger a build).support: Faraday waits for its support team.force_updateis refused with409 Conflict, and no build will pick up your changes until support acts.- Omitted: nothing blocks a rebuild. Faraday builds it again when an upstream resource produces new output or its schedule comes up, which may not happen soon; a configuration change or
force_updateworks too.
Upstream changes
A resource can be current with its own configuration and still behind its inputs. GET /graph returns one edge for each dependency, with both ends' 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. Because last_read_input_at updates only when a build finishes (alongside last_updated_output_at when its output changed), walking the edges downstream from a finished change and checking that comparison (plus downstream_status for error) at each step follows the change through the whole pipeline.
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. Neither tells you whether your current configuration has built. Use last_updated_config_at and last_read_input_at.