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

FieldWhat it records
last_updated_config_atWhen 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_atWhen the latest finished build started reading the resource's configuration and inputs. Omitted until a build finishes (whether ready or error).
last_updated_output_atWhen 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.
statusThe state of the latest build: new (never built), starting, running, ready, or error.
status_changed_atWhen status last changed. Use it to bound how long you wait on an in-flight build or an error.
status_errorThe error message, when status is error.
status_needs_fix_fromWhat 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:

  • ready means your configuration took effect.
  • error means the build failed (see status_error and status_needs_fix_from).
  • starting or running means an earlier build with your configuration finished and a later build is now running. Because failed builds also advance last_read_input_at, that earlier build succeeded if last_updated_output_at is at or after last_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 until status is ready or error.

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 name triggers no build and returns the previous last_updated_config_at, which a built resource's last_read_input_at has 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 reads directory. Re-read the dataset or atlas afterward if you need the last_updated_config_at that 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 call force_update on it (changing only name, or updating an upstream resource, does not clear user).
  • support: Faraday waits for its support team. force_update is refused with 409 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_update to retry immediately, or use status_changed_at to 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:

  1. Check every hop; do not compare endpoints directly. Faraday places managed streams and traits between a dataset and a cohort. Also, if an intermediate resource rebuilds on new input and its own output does not change, its last_updated_output_at stays put and Faraday skips rebuilding what sits below it. Checking each edge on GET /graph sees that the pipeline is caught up; comparing a target's last_read_input_at directly to a dataset's last_updated_output_at can wait forever.
  2. Stop on frozen downstream errors. If a downstream resource has downstream_status of error and downstream_status_needs_fix_from of user or support, Faraday will not rebuild it when an upstream produces new output. Treat that downstream as failed rather than waiting for downstream_last_read_input_at to advance.
  3. GET /graph lists edges, not standalone resources. A resource with no upstream or downstream dependencies yet (such as a new connection, place, or attribute-only cohort before a scope uses it) has no edges and is absent from GET /graph. Read standalone resources with GET /<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.