Docs

run

Job-run history, reports, and tasks persisted by the Amfelt agent.

Amfelt REST API · v1.13.0 · https://api.amfelt.com

GET /v1/runs/metrics  

Get run metrics aggregate.

Returns aggregate metrics for job runs in the caller’s organization within the specified time window, optionally filtered by project and environment.

Parameters  

NameInRequiredTypeDescription
X-Tenant-SlugheaderYesstringSlug of the organization to scope the request to; required for user-authenticated requests.
Slug of the organization to scope the request to; required for user-authenticated requests.
projectqueryNostringFilter metrics by project uuid.
Filter metrics by project uuid.
envqueryNostringFilter metrics by DTAP environment slug.
Filter metrics by DTAP environment slug.
windowqueryNostring (enum: 24h, 7d, 30d)Time window for the aggregate.
Time window for the aggregate.

Responses  

200 Run metrics aggregate for the requested window.

application/json

PropertyTypeRequiredDescription
avg_duration_msnumberYesAverage run duration in milliseconds (COALESCE 0 when no completed runs).
Average run duration in milliseconds (COALESCE 0 when no completed runs).
failedintegerYesNumber of runs that ended in failure.
Number of runs that ended in failure.
p95_duration_msnumberYes95th-percentile run duration in milliseconds (COALESCE 0 when no completed runs).
95th-percentile run duration in milliseconds (COALESCE 0 when no completed runs).
runningintegerYesNumber of runs currently in progress.
Number of runs currently in progress.
succeededintegerYesNumber of runs that completed successfully.
Number of runs that completed successfully.
totalintegerYesTotal number of runs in the window.
Total number of runs in the window.
total_bytesintegerYesSum of run telemetry bytes over the requested window/project/env scope.
Sum of run telemetry bytes over the requested window/project/env scope.
total_rowsintegerYesSum of run telemetry rows over the requested window/project/env scope.
Sum of run telemetry rows over the requested window/project/env scope.
400 The request was malformed or failed validation.

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.
401 The request lacks valid credentials.

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.

Security  

bearer_jwt

GET /v1/runs  

List job runs.

Returns a page of job runs for the caller’s organization, optionally filtered by job name, status, project, environment, source, or time window.

Parameters  

NameInRequiredTypeDescription
X-Tenant-SlugheaderYesstringSlug of the organization to scope the request to; required for user-authenticated requests.
Slug of the organization to scope the request to; required for user-authenticated requests.
jobqueryNostringFilter job runs by job name.
Filter job runs by job name.
statusqueryNostringFilter job runs by status.
Filter job runs by status.
cursorqueryNostringOpaque cursor for the next page; pass back the ’next_cursor’ from a prior response.
Opaque cursor for the next page; pass back the ’next_cursor’ from a prior response.
limitqueryNointegerMaximum number of items to return per page.
Maximum number of items to return per page.
projectqueryNostringFilter runs by project uuid.
Filter runs by project uuid.
envqueryNostringFilter runs by DTAP environment slug.
Filter runs by DTAP environment slug.
sourcequeryNostringFilter runs by source name.
Filter runs by source name.
windowqueryNostring (enum: 24h, 7d, 30d)Limit returned runs to a relative time window. When omitted, no time filter is applied.
Limit returned runs to a relative time window. When omitted, no time filter is applied.

Responses  

200 A page of job runs.

application/json

PropertyTypeRequiredDescription
dataRun []YesThe page of job runs.
The page of job runs.
next_cursor[string null]NoOpaque cursor for the next page, or null when this is the final page. Examples: eyJpZCI6OTk5fQ.
Opaque cursor for the next page, or null when this is the final page. Examples: eyJpZCI6OTk5fQ.
400 The request was malformed or failed validation.

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.
401 The request lacks valid credentials.

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.

Security  

bearer_jwt

POST /v1/runs  

Create a job run.

Records a new job run. The organization is derived from the agent credentials; any organization_id in the body is ignored.

Request body (required)  

application/json

PropertyTypeRequiredDescription
agent_idstringYesIdentifier of the agent executing the run.
Identifier of the agent executing the run.
cmd_idstringNoCorrelation key from the cmd.execute_flow dispatch that started this run.
Correlation key from the cmd.execute_flow dispatch that started this run.
config_commit_sha[string null]NoFull SHA of the configuration commit the run executes (ADR-129 decisions 1 and 11). Null with config_source draft means the agent did not hold a commit byte for byte. Absent or null with no config_source means unknown: the run was reported by an older agent that does not send its commit. Examples: 8f14e45fceea167a5a36dedd4bea2543c3a6f7b2.
Full SHA of the configuration commit the run executes (ADR-129 decisions 1 and 11). Null with config_source draft means the agent did not hold a commit byte for byte. Absent or null with no config_source means unknown: the run was reported by an older agent that does not send its commit. Examples: 8f14e45fceea167a5a36dedd4bea2543c3a6f7b2.
config_source[string null]NoWhere the run’s configuration came from. commit means the agent held the commit config_commit_sha byte for byte; draft means its configuration was written by a file-form deploy or a local edit, so it matches no commit and config_commit_sha is null. Absent or null means unknown: the run was reported by an older agent, never draft. Valid values are: commit, draft. Examples: commit.
Where the run’s configuration came from. commit means the agent held the commit config_commit_sha byte for byte; draft means its configuration was written by a file-form deploy or a local edit, so it matches no commit and config_commit_sha is null. Absent or null means unknown: the run was reported by an older agent, never draft. Valid values are: commit, draft. Examples: commit.
environmentstringNoDTAP environment slug the run ran in; resolved to FK server-side.
DTAP environment slug the run ran in; resolved to FK server-side.
job_namestringYesName of the job that produced the run. Examples: sales-to-dwh.
Name of the job that produced the run. Examples: sales-to-dwh.
object_countintegerNoNumber of objects the run will process.
Number of objects the run will process.
run_idintegerYesClient-assigned unique identifier of the run. Examples: 20260412120000000.
Client-assigned unique identifier of the run. Examples: 20260412120000000.
sourcestringNoName of the source the run processed; identifies the project server-side.
Name of the source the run processed; identifies the project server-side.
started_atstringYesTimestamp when the run started.
Timestamp when the run started.
statusstringNoInitial lifecycle status; defaults to ‘started’ when omitted. Examples: started.
Initial lifecycle status; defaults to ‘started’ when omitted. Examples: started.

Responses  

201 The job run was created.

application/json

PropertyTypeRequiredDescription
run_idintegerYesIdentifier of the run. Examples: 20260412120000000.
Identifier of the run. Examples: 20260412120000000.
400 The request was malformed or failed validation.

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.
401 The request lacks valid credentials.

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.
409 The request conflicts with the current state of the resource.

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.

Security  

bearer_jwt

DELETE /v1/runs  

Purge job runs.

Permanently deletes every run, task, and checkpoint for the caller’s organization.

Responses  

204 The runs were purged.
401 The request lacks valid credentials.

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.

Security  

bearer_jwt

GET /v1/runs/{run_id}/tasks  

List run tasks.

Returns a page of tasks executed during a job run.

Parameters  

NameInRequiredTypeDescription
X-Tenant-SlugheaderYesstringSlug of the organization to scope the request to; required for user-authenticated requests.
Slug of the organization to scope the request to; required for user-authenticated requests.
run_idpathYesintegerIdentifier of the job run.
Identifier of the job run.
cursorqueryNostringOpaque cursor for the next page; pass back the ’next_cursor’ from a prior response.
Opaque cursor for the next page; pass back the ’next_cursor’ from a prior response.
limitqueryNointegerMaximum number of items to return per page.
Maximum number of items to return per page.

Responses  

200 A page of run tasks.

application/json

PropertyTypeRequiredDescription
dataTask []YesThe page of tasks.
The page of tasks.
next_cursor[string null]NoOpaque cursor for the next page, or null when this is the final page. Examples: eyJpZCI6OTk5fQ.
Opaque cursor for the next page, or null when this is the final page. Examples: eyJpZCI6OTk5fQ.
401 The request lacks valid credentials.

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.
404 The specified resource was not found.

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.

Security  

bearer_jwt

POST /v1/runs/{run_id}/rerun  

Rerun the objects of a finished run that did not succeed.

Starts a new run of the same job in the same environment that loads only the objects that did not succeed in the given run: an object is skipped when all of its tasks in that run succeeded, so failed objects and objects the run never started are loaded again. Dispatches a cmd.execute_flow command to the environment’s agent and returns immediately. The new run records trigger rerun and rerun_of_run_id. The rerun runs at the configuration commit the original run recorded; when it recorded none, it runs at the current commit, and commit_basis says which. One audit event is written per rerun: object type run, action create, detail operation rerun.

Parameters  

NameInRequiredTypeDescription
run_idpathYesintegerIdentifier of the job run.
Identifier of the job run.

Responses  

202 Rerun dispatched to the environment's agent. When the agent is offline, status is queued_offline and the command is delivered when it reconnects, as for a manual run.

application/json

Child elements:
401 The request lacks valid credentials.

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.
403 The caller is authenticated but not permitted to perform the request.

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.
404 Code not_found: the run does not exist. Nothing is dispatched.

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.
409 The run cannot be rerun in its current state. Nothing is dispatched. The causes are: every object of the run succeeded, answered with "nothing to rerun" (code conflict); the run has not finished, answered with "run is still running" (code conflict); another run of the same job is running, answered with "job is running" (code conflict); the agent is below the version that can skip objects, answered with "upgrade the agent to <floor> or later to rerun failed objects", where <floor> is that version (code agent_upgrade_required); the project is archived (code project_archived).

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.

Security  

bearer_jwt

GET /v1/runs/{run_id}/report  

Get a run report.

Returns the report and optional remedy attached to a job run.

Parameters  

NameInRequiredTypeDescription
X-Tenant-SlugheaderYesstringSlug of the organization to scope the request to; required for user-authenticated requests.
Slug of the organization to scope the request to; required for user-authenticated requests.
run_idpathYesintegerIdentifier of the job run.
Identifier of the job run.

Responses  

200 The run report.

application/json

PropertyTypeRequiredDescription
remedyobjectNoOptional structured remedy describing how to resolve a failed run.
Optional structured remedy describing how to resolve a failed run.
reportobjectYesStructured report describing the run outcome.
Structured report describing the run outcome.
401 The request lacks valid credentials.

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.
404 The specified resource was not found.

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.

Security  

bearer_jwt

PUT /v1/runs/{run_id}/report  

Set a run report.

Attaches a report and optional remedy to a job run.

Parameters  

NameInRequiredTypeDescription
run_idpathYesintegerIdentifier of the job run.
Identifier of the job run.

Request body (required)  

application/json

PropertyTypeRequiredDescription
remedyobjectNoOptional structured remedy describing how to resolve a failed run.
Optional structured remedy describing how to resolve a failed run.
reportobjectYesStructured report describing the run outcome.
Structured report describing the run outcome.

Responses  

200 The run report was stored.

application/json

PropertyTypeRequiredDescription
run_idintegerYesIdentifier of the run. Examples: 20260412120000000.
Identifier of the run. Examples: 20260412120000000.
400 The request was malformed or failed validation.

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.
401 The request lacks valid credentials.

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.
404 The specified resource was not found.

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.

Security  

bearer_jwt

GET /v1/runs/{run_id}/detail  

Get run detail.

Returns the projected checkpoint tree for a job run as a flat phase/task viewer model (ADR-050/ADR-057). Roots are parent_id IS NULL checkpoints; phases are each root’s direct children; tasks are each phase’s children.

Parameters  

NameInRequiredTypeDescription
X-Tenant-SlugheaderYesstringSlug of the organization to scope the request to; required for user-authenticated requests.
Slug of the organization to scope the request to; required for user-authenticated requests.
run_idpathYesintegerIdentifier of the job run.
Identifier of the job run.

Responses  

200 The run detail projection.

application/json

PropertyTypeRequiredDescription
config_commit_sha[string null]NoFull SHA of the configuration commit the run executed (ADR-129 decisions 1 and 11). Null with config_source draft means the agent did not hold a commit byte for byte. Absent or null with no config_source means unknown: the run was reported by an older agent that does not send its commit. Examples: 8f14e45fceea167a5a36dedd4bea2543c3a6f7b2.
Full SHA of the configuration commit the run executed (ADR-129 decisions 1 and 11). Null with config_source draft means the agent did not hold a commit byte for byte. Absent or null with no config_source means unknown: the run was reported by an older agent that does not send its commit. Examples: 8f14e45fceea167a5a36dedd4bea2543c3a6f7b2.
config_source[string null]NoWhere the run’s configuration came from. commit means the agent held the commit config_commit_sha byte for byte; draft means its configuration was written by a file-form deploy or a local edit, so it matches no commit and config_commit_sha is null. Absent or null means unknown: the run was reported by an older agent, never draft. Valid values are: commit, draft. Examples: commit.
Where the run’s configuration came from. commit means the agent held the commit config_commit_sha byte for byte; draft means its configuration was written by a file-form deploy or a local edit, so it matches no commit and config_commit_sha is null. Absent or null means unknown: the run was reported by an older agent, never draft. Valid values are: commit, draft. Examples: commit.
idstringYesRun identifier (string representation of run_id).
Run identifier (string representation of run_id).
phasesRunPhase []YesOrdered list of run phases projected from the checkpoint tree.
Ordered list of run phases projected from the checkpoint tree.
statusstringYesViewer status of the run. Valid values are: pending, running, done, failed, warning.
Viewer status of the run. Valid values are: pending, running, done, failed, warning.
strategy[string null]NoLoad strategy the run was dispatched with; the strategy actually applied per object is reported on its tasks. null = not reported (older agent or older run). Valid values are: full, incremental, window, full_reload. Examples: incremental.
Load strategy the run was dispatched with; the strategy actually applied per object is reported on its tasks. null = not reported (older agent or older run). Valid values are: full, incremental, window, full_reload. Examples: incremental.
401 The request lacks valid credentials.

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.
404 The specified resource was not found.

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.

Security  

bearer_jwt

POST /v1/runs/{run_id}/cancel  

Request cancellation of an in-flight run.

Dispatches a cmd.stop_job command to the run’s assigned agent. The run status transitions to cancelled asynchronously via the agent’s run_finished telemetry; the endpoint returns immediately.

Parameters  

NameInRequiredTypeDescription
run_idpathYesintegerIdentifier of the job run.
Identifier of the job run.

Responses  

202 Cancellation dispatched to the run's agent.
401 The request lacks valid credentials.

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.
404 The specified resource was not found.

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.
409 Run already terminal; nothing to cancel.

Security  

bearer_jwt

GET /v1/runs/{run_id}  

Get a job run.

Returns a single job run by identifier.

Parameters  

NameInRequiredTypeDescription
X-Tenant-SlugheaderYesstringSlug of the organization to scope the request to; required for user-authenticated requests.
Slug of the organization to scope the request to; required for user-authenticated requests.
run_idpathYesintegerIdentifier of the job run.
Identifier of the job run.

Responses  

200 The job run.

application/json

PropertyTypeRequiredDescription
agent_idstringYesIdentifier of the agent that executed the run.
Identifier of the agent that executed the run.
cmd_id[string null]NoCorrelation key from the cmd.execute_flow dispatch that started the run. Always present on the wire; null means the run was agent-local or CLI-started rather than dispatched by the control plane. Present alongside a null schedule_name, it means the run was dispatched and no schedule was recorded for it — with no claim about why. Examples: 0f3a9b6c-1d24-4c9e-8a71-5b2f0c8d4e13.
Correlation key from the cmd.execute_flow dispatch that started the run. Always present on the wire; null means the run was agent-local or CLI-started rather than dispatched by the control plane. Present alongside a null schedule_name, it means the run was dispatched and no schedule was recorded for it — with no claim about why. Examples: 0f3a9b6c-1d24-4c9e-8a71-5b2f0c8d4e13.
config_commit_sha[string null]NoFull SHA of the configuration commit the run executed (ADR-129 decisions 1 and 11). Null with config_source draft means the agent did not hold a commit byte for byte. Absent or null with no config_source means unknown: the run was reported by an older agent that does not send its commit. Examples: 8f14e45fceea167a5a36dedd4bea2543c3a6f7b2.
Full SHA of the configuration commit the run executed (ADR-129 decisions 1 and 11). Null with config_source draft means the agent did not hold a commit byte for byte. Absent or null with no config_source means unknown: the run was reported by an older agent that does not send its commit. Examples: 8f14e45fceea167a5a36dedd4bea2543c3a6f7b2.
config_source[string null]NoWhere the run’s configuration came from. commit means the agent held the commit config_commit_sha byte for byte; draft means its configuration was written by a file-form deploy or a local edit, so it matches no commit and config_commit_sha is null. Absent or null means unknown: the run was reported by an older agent, never draft. Valid values are: commit, draft. Examples: commit.
Where the run’s configuration came from. commit means the agent held the commit config_commit_sha byte for byte; draft means its configuration was written by a file-form deploy or a local edit, so it matches no commit and config_commit_sha is null. Absent or null means unknown: the run was reported by an older agent, never draft. Valid values are: commit, draft. Examples: commit.
created_atstringYesTimestamp when the run record was created.
Timestamp when the run record was created.
duration_msintegerNoTotal run duration in milliseconds; absent while in progress.
Total run duration in milliseconds; absent while in progress.
environment[string null]NoDTAP environment slug the run ran in.
DTAP environment slug the run ran in.
error_countintegerNoNumber of errors recorded during the run.
Number of errors recorded during the run.
finished_atstringNoTimestamp when the run finished; absent while in progress.
Timestamp when the run finished; absent while in progress.
job_namestringYesName of the job that produced the run. Examples: sales-to-dwh.
Name of the job that produced the run. Examples: sales-to-dwh.
object_countintegerNoNumber of objects processed by the run.
Number of objects processed by the run.
organization_idstringYesIdentifier of the owning organization.
Identifier of the owning organization.
project[string null]NoProject uuid the run is scoped to; resolved server-side from the source.
Project uuid the run is scoped to; resolved server-side from the source.
rerun_of_run_id[integer null]NoIdentifier of the run this run repeats; set only when trigger is rerun. Null on every other run, and when the original run no longer exists. Examples: 20260412120000000.
Identifier of the run this run repeats; set only when trigger is rerun. Null on every other run, and when the original run no longer exists. Examples: 20260412120000000.
run_idintegerYesUnique identifier of the run. Examples: 20260412120000000.
Unique identifier of the run. Examples: 20260412120000000.
schedule_name[string null]NoName of the scheduled entry that dispatched the run, resolved server-side at ingest. Joins to ScheduleState.run_name, not to ScheduleState.schedule, which is a cron expression. Always present on the wire; null means no schedule name is recorded for this run, which cmd_id disambiguates — a null cmd_id means the run was agent-local and genuinely had no schedule, while a cmd_id with no schedule name means the run was dispatched and no schedule was recorded for it. That second case carries no claim about why, and must not be rendered as one. Examples: nightly.
Name of the scheduled entry that dispatched the run, resolved server-side at ingest. Joins to ScheduleState.run_name, not to ScheduleState.schedule, which is a cron expression. Always present on the wire; null means no schedule name is recorded for this run, which cmd_id disambiguates — a null cmd_id means the run was agent-local and genuinely had no schedule, while a cmd_id with no schedule name means the run was dispatched and no schedule was recorded for it. That second case carries no claim about why, and must not be rendered as one. Examples: nightly.
source[string null]NoName of the source that produced the run; resolved from agent-emitted names.
Name of the source that produced the run; resolved from agent-emitted names.
started_atstringYesTimestamp when the run started.
Timestamp when the run started.
statusstringYesLifecycle status of the run. Examples: finished.
Lifecycle status of the run. Examples: finished.
strategy[string null]NoLoad strategy the run was dispatched with; the strategy actually applied per object is reported on its tasks. null = not reported (older agent or older run). Valid values are: full, incremental, window, full_reload. Examples: incremental.
Load strategy the run was dispatched with; the strategy actually applied per object is reported on its tasks. null = not reported (older agent or older run). Valid values are: full, incremental, window, full_reload. Examples: incremental.
tables_failedintegerNoNumber of tables that failed.
Number of tables that failed.
tables_okintegerNoNumber of tables that completed successfully.
Number of tables that completed successfully.
tables_waitingintegerNoNumber of tables the run loaded to staging and then stopped there because their classification waits (ObjectWaitReason): for a person’s approval of a proposal (awaiting_approval), for a person’s confirmation of a history rebuild (awaiting_rebuild_confirmation), or for a classification (awaiting_classification). A waiting table is not a failure, so a run with waiting tables can still read finished; this count is what keeps that partial load visible. Absent when the run did not report it (an agent or api older than this field).
Number of tables the run loaded to staging and then stopped there because their classification waits (ObjectWaitReason): for a person’s approval of a proposal (awaiting_approval), for a person’s confirmation of a history rebuild (awaiting_rebuild_confirmation), or for a classification (awaiting_classification). A waiting table is not a failure, so a run with waiting tables can still read finished; this count is what keeps that partial load visible. Absent when the run did not report it (an agent or api older than this field).
total_bytesintegerNoTotal bytes processed across all tasks.
Total bytes processed across all tasks.
total_rowsintegerNoTotal rows processed across all tasks.
Total rows processed across all tasks.
triggerstringNoHow the run was started: manual by an operator, schedule by the scheduler, or rerun of the failed objects of an earlier run. Absent when the api does not report it. Valid values are: manual, schedule, rerun. Examples: manual.
How the run was started: manual by an operator, schedule by the scheduler, or rerun of the failed objects of an earlier run. Absent when the api does not report it. Valid values are: manual, schedule, rerun. Examples: manual.
warning_countintegerNoNumber of warnings recorded during the run.
Number of warnings recorded during the run.
401 The request lacks valid credentials.

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.
404 The specified resource was not found.

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.

Security  

bearer_jwt

PUT /v1/runs/{run_id}  

Update a job run.

Updates the status and metrics of an existing job run.

Parameters  

NameInRequiredTypeDescription
run_idpathYesintegerIdentifier of the job run.
Identifier of the job run.

Request body (required)  

application/json

PropertyTypeRequiredDescription
duration_msintegerNoTotal run duration in milliseconds.
Total run duration in milliseconds.
error_countintegerNoNumber of errors recorded during the run.
Number of errors recorded during the run.
finished_atstringNoTimestamp when the run finished.
Timestamp when the run finished.
statusstringYesNew lifecycle status of the run. Examples: finished.
New lifecycle status of the run. Examples: finished.
tables_failedintegerNoNumber of tables that failed.
Number of tables that failed.
tables_okintegerNoNumber of tables that completed successfully.
Number of tables that completed successfully.
tables_waitingintegerNoNumber of tables the run loaded to staging and then stopped there, waiting on their classification (ObjectWaitReason). Read back as Run.tables_waiting. An agent older than this field omits it.
Number of tables the run loaded to staging and then stopped there, waiting on their classification (ObjectWaitReason). Read back as Run.tables_waiting. An agent older than this field omits it.
total_bytesintegerNoTotal bytes processed across all tasks.
Total bytes processed across all tasks.
total_rowsintegerNoTotal rows processed across all tasks.
Total rows processed across all tasks.
warning_countintegerNoNumber of warnings recorded during the run.
Number of warnings recorded during the run.

Responses  

200 The job run was updated.

application/json

PropertyTypeRequiredDescription
run_idintegerYesIdentifier of the run. Examples: 20260412120000000.
Identifier of the run. Examples: 20260412120000000.
400 The request was malformed or failed validation.

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.
401 The request lacks valid credentials.

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.
404 The specified resource was not found.

application/json

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.

Security  

bearer_jwt

Schemas  

Run Metrics  

type: RunMetrics

Aggregate metrics for job runs within a time window.

PropertyTypeRequiredDescription
avg_duration_msnumberYesAverage run duration in milliseconds (COALESCE 0 when no completed runs).
Average run duration in milliseconds (COALESCE 0 when no completed runs).
failedintegerYesNumber of runs that ended in failure.
Number of runs that ended in failure.
p95_duration_msnumberYes95th-percentile run duration in milliseconds (COALESCE 0 when no completed runs).
95th-percentile run duration in milliseconds (COALESCE 0 when no completed runs).
runningintegerYesNumber of runs currently in progress.
Number of runs currently in progress.
succeededintegerYesNumber of runs that completed successfully.
Number of runs that completed successfully.
totalintegerYesTotal number of runs in the window.
Total number of runs in the window.
total_bytesintegerYesSum of run telemetry bytes over the requested window/project/env scope.
Sum of run telemetry bytes over the requested window/project/env scope.
total_rowsintegerYesSum of run telemetry rows over the requested window/project/env scope.
Sum of run telemetry rows over the requested window/project/env scope.

Error  

type: Error

The standard error envelope returned by every non-2xx response.

PropertyTypeRequiredDescription
codestringYesStable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
Stable, snake_case token identifying the error condition. See ErrorCode for the api’s canonical named vocabulary — this field is deliberately not restricted to it, since handlers may emit other ad-hoc codes not listed there (e.g. not_implemented). Examples: invalid_argument.
fieldstringNoOptional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
Optional hint identifying the request field the error refers to, in snake_case (e.g. “slug”, “display_name”, “token”). Set by handlers that validate multiple fields and want to enable field-targeted UX in clients. Absent when the error does not map to a single field. Examples: slug.
messagestringYesHuman-readable description of the error. Examples: limit must be between 1 and 100.
Human-readable description of the error. Examples: limit must be between 1 and 100.

Run List  

type: RunList

A page of job runs.

PropertyTypeRequiredDescription
dataRun []YesThe page of job runs.
The page of job runs.
next_cursor[string null]NoOpaque cursor for the next page, or null when this is the final page. Examples: eyJpZCI6OTk5fQ.
Opaque cursor for the next page, or null when this is the final page. Examples: eyJpZCI6OTk5fQ.

Run  

type: Run

A job run executed by the Amfelt agent.

PropertyTypeRequiredDescription
agent_idstringYesIdentifier of the agent that executed the run.
Identifier of the agent that executed the run.
cmd_id[string null]NoCorrelation key from the cmd.execute_flow dispatch that started the run. Always present on the wire; null means the run was agent-local or CLI-started rather than dispatched by the control plane. Present alongside a null schedule_name, it means the run was dispatched and no schedule was recorded for it — with no claim about why. Examples: 0f3a9b6c-1d24-4c9e-8a71-5b2f0c8d4e13.
Correlation key from the cmd.execute_flow dispatch that started the run. Always present on the wire; null means the run was agent-local or CLI-started rather than dispatched by the control plane. Present alongside a null schedule_name, it means the run was dispatched and no schedule was recorded for it — with no claim about why. Examples: 0f3a9b6c-1d24-4c9e-8a71-5b2f0c8d4e13.
config_commit_sha[string null]NoFull SHA of the configuration commit the run executed (ADR-129 decisions 1 and 11). Null with config_source draft means the agent did not hold a commit byte for byte. Absent or null with no config_source means unknown: the run was reported by an older agent that does not send its commit. Examples: 8f14e45fceea167a5a36dedd4bea2543c3a6f7b2.
Full SHA of the configuration commit the run executed (ADR-129 decisions 1 and 11). Null with config_source draft means the agent did not hold a commit byte for byte. Absent or null with no config_source means unknown: the run was reported by an older agent that does not send its commit. Examples: 8f14e45fceea167a5a36dedd4bea2543c3a6f7b2.
config_source[string null]NoWhere the run’s configuration came from. commit means the agent held the commit config_commit_sha byte for byte; draft means its configuration was written by a file-form deploy or a local edit, so it matches no commit and config_commit_sha is null. Absent or null means unknown: the run was reported by an older agent, never draft. Valid values are: commit, draft. Examples: commit.
Where the run’s configuration came from. commit means the agent held the commit config_commit_sha byte for byte; draft means its configuration was written by a file-form deploy or a local edit, so it matches no commit and config_commit_sha is null. Absent or null means unknown: the run was reported by an older agent, never draft. Valid values are: commit, draft. Examples: commit.
created_atstringYesTimestamp when the run record was created.
Timestamp when the run record was created.
duration_msintegerNoTotal run duration in milliseconds; absent while in progress.
Total run duration in milliseconds; absent while in progress.
environment[string null]NoDTAP environment slug the run ran in.
DTAP environment slug the run ran in.
error_countintegerNoNumber of errors recorded during the run.
Number of errors recorded during the run.
finished_atstringNoTimestamp when the run finished; absent while in progress.
Timestamp when the run finished; absent while in progress.
job_namestringYesName of the job that produced the run. Examples: sales-to-dwh.
Name of the job that produced the run. Examples: sales-to-dwh.
object_countintegerNoNumber of objects processed by the run.
Number of objects processed by the run.
organization_idstringYesIdentifier of the owning organization.
Identifier of the owning organization.
project[string null]NoProject uuid the run is scoped to; resolved server-side from the source.
Project uuid the run is scoped to; resolved server-side from the source.
rerun_of_run_id[integer null]NoIdentifier of the run this run repeats; set only when trigger is rerun. Null on every other run, and when the original run no longer exists. Examples: 20260412120000000.
Identifier of the run this run repeats; set only when trigger is rerun. Null on every other run, and when the original run no longer exists. Examples: 20260412120000000.
run_idintegerYesUnique identifier of the run. Examples: 20260412120000000.
Unique identifier of the run. Examples: 20260412120000000.
schedule_name[string null]NoName of the scheduled entry that dispatched the run, resolved server-side at ingest. Joins to ScheduleState.run_name, not to ScheduleState.schedule, which is a cron expression. Always present on the wire; null means no schedule name is recorded for this run, which cmd_id disambiguates — a null cmd_id means the run was agent-local and genuinely had no schedule, while a cmd_id with no schedule name means the run was dispatched and no schedule was recorded for it. That second case carries no claim about why, and must not be rendered as one. Examples: nightly.
Name of the scheduled entry that dispatched the run, resolved server-side at ingest. Joins to ScheduleState.run_name, not to ScheduleState.schedule, which is a cron expression. Always present on the wire; null means no schedule name is recorded for this run, which cmd_id disambiguates — a null cmd_id means the run was agent-local and genuinely had no schedule, while a cmd_id with no schedule name means the run was dispatched and no schedule was recorded for it. That second case carries no claim about why, and must not be rendered as one. Examples: nightly.
source[string null]NoName of the source that produced the run; resolved from agent-emitted names.
Name of the source that produced the run; resolved from agent-emitted names.
started_atstringYesTimestamp when the run started.
Timestamp when the run started.
statusstringYesLifecycle status of the run. Examples: finished.
Lifecycle status of the run. Examples: finished.
strategy[string null]NoLoad strategy the run was dispatched with; the strategy actually applied per object is reported on its tasks. null = not reported (older agent or older run). Valid values are: full, incremental, window, full_reload. Examples: incremental.
Load strategy the run was dispatched with; the strategy actually applied per object is reported on its tasks. null = not reported (older agent or older run). Valid values are: full, incremental, window, full_reload. Examples: incremental.
tables_failedintegerNoNumber of tables that failed.
Number of tables that failed.
tables_okintegerNoNumber of tables that completed successfully.
Number of tables that completed successfully.
tables_waitingintegerNoNumber of tables the run loaded to staging and then stopped there because their classification waits (ObjectWaitReason): for a person’s approval of a proposal (awaiting_approval), for a person’s confirmation of a history rebuild (awaiting_rebuild_confirmation), or for a classification (awaiting_classification). A waiting table is not a failure, so a run with waiting tables can still read finished; this count is what keeps that partial load visible. Absent when the run did not report it (an agent or api older than this field).
Number of tables the run loaded to staging and then stopped there because their classification waits (ObjectWaitReason): for a person’s approval of a proposal (awaiting_approval), for a person’s confirmation of a history rebuild (awaiting_rebuild_confirmation), or for a classification (awaiting_classification). A waiting table is not a failure, so a run with waiting tables can still read finished; this count is what keeps that partial load visible. Absent when the run did not report it (an agent or api older than this field).
total_bytesintegerNoTotal bytes processed across all tasks.
Total bytes processed across all tasks.
total_rowsintegerNoTotal rows processed across all tasks.
Total rows processed across all tasks.
triggerstringNoHow the run was started: manual by an operator, schedule by the scheduler, or rerun of the failed objects of an earlier run. Absent when the api does not report it. Valid values are: manual, schedule, rerun. Examples: manual.
How the run was started: manual by an operator, schedule by the scheduler, or rerun of the failed objects of an earlier run. Absent when the api does not report it. Valid values are: manual, schedule, rerun. Examples: manual.
warning_countintegerNoNumber of warnings recorded during the run.
Number of warnings recorded during the run.

Run Create  

type: RunCreate

The payload to create a job run.

PropertyTypeRequiredDescription
agent_idstringYesIdentifier of the agent executing the run.
Identifier of the agent executing the run.
cmd_idstringNoCorrelation key from the cmd.execute_flow dispatch that started this run.
Correlation key from the cmd.execute_flow dispatch that started this run.
config_commit_sha[string null]NoFull SHA of the configuration commit the run executes (ADR-129 decisions 1 and 11). Null with config_source draft means the agent did not hold a commit byte for byte. Absent or null with no config_source means unknown: the run was reported by an older agent that does not send its commit. Examples: 8f14e45fceea167a5a36dedd4bea2543c3a6f7b2.
Full SHA of the configuration commit the run executes (ADR-129 decisions 1 and 11). Null with config_source draft means the agent did not hold a commit byte for byte. Absent or null with no config_source means unknown: the run was reported by an older agent that does not send its commit. Examples: 8f14e45fceea167a5a36dedd4bea2543c3a6f7b2.
config_source[string null]NoWhere the run’s configuration came from. commit means the agent held the commit config_commit_sha byte for byte; draft means its configuration was written by a file-form deploy or a local edit, so it matches no commit and config_commit_sha is null. Absent or null means unknown: the run was reported by an older agent, never draft. Valid values are: commit, draft. Examples: commit.
Where the run’s configuration came from. commit means the agent held the commit config_commit_sha byte for byte; draft means its configuration was written by a file-form deploy or a local edit, so it matches no commit and config_commit_sha is null. Absent or null means unknown: the run was reported by an older agent, never draft. Valid values are: commit, draft. Examples: commit.
environmentstringNoDTAP environment slug the run ran in; resolved to FK server-side.
DTAP environment slug the run ran in; resolved to FK server-side.
job_namestringYesName of the job that produced the run. Examples: sales-to-dwh.
Name of the job that produced the run. Examples: sales-to-dwh.
object_countintegerNoNumber of objects the run will process.
Number of objects the run will process.
run_idintegerYesClient-assigned unique identifier of the run. Examples: 20260412120000000.
Client-assigned unique identifier of the run. Examples: 20260412120000000.
sourcestringNoName of the source the run processed; identifies the project server-side.
Name of the source the run processed; identifies the project server-side.
started_atstringYesTimestamp when the run started.
Timestamp when the run started.
statusstringNoInitial lifecycle status; defaults to ‘started’ when omitted. Examples: started.
Initial lifecycle status; defaults to ‘started’ when omitted. Examples: started.

Run Ref  

type: RunRef

A reference to a job run.

PropertyTypeRequiredDescription
run_idintegerYesIdentifier of the run. Examples: 20260412120000000.
Identifier of the run. Examples: 20260412120000000.

Task List  

type: TaskList

A page of run tasks.

PropertyTypeRequiredDescription
dataTask []YesThe page of tasks.
The page of tasks.
next_cursor[string null]NoOpaque cursor for the next page, or null when this is the final page. Examples: eyJpZCI6OTk5fQ.
Opaque cursor for the next page, or null when this is the final page. Examples: eyJpZCI6OTk5fQ.

Task  

type: Task

A task executed within a job run.

PropertyTypeRequiredDescription
bytes_processedintegerNoNumber of bytes processed.
Number of bytes processed.
duration_msintegerNoTask duration in milliseconds.
Task duration in milliseconds.
error_codeintegerNoOptional error code recorded for the task.
Optional error code recorded for the task.
error_messagestringNoOptional error message recorded for the task.
Optional error message recorded for the task.
finished_atstringNoTimestamp when the task finished.
Timestamp when the task finished.
layer_idstringYesIdentifier of the layer the task processed.
Identifier of the layer the task processed.
object_idstringYesIdentifier of the object the task processed.
Identifier of the object the task processed.
rows_conflictintegerNoNumber of rows that hit a conflict.
Number of rows that hit a conflict.
rows_insertedintegerNoNumber of rows inserted.
Number of rows inserted.
rows_late_arrivalintegerNoNumber of late-arriving rows.
Number of late-arriving rows.
rows_processedintegerNoNumber of rows processed.
Number of rows processed.
rows_reconcile_mismatchintegerNoSigned row-count reconciliation gap (extract minus landed staging count); 0 = clean.
Signed row-count reconciliation gap (extract minus landed staging count); 0 = clean.
rows_skippedintegerNoNumber of rows skipped.
Number of rows skipped.
rows_updatedintegerNoNumber of rows updated.
Number of rows updated.
run_idintegerYesIdentifier of the run the task belongs to.
Identifier of the run the task belongs to.
skip_reasonstringNoSet when the run deliberately did not run this layer for the object, with the reason as the agent reported it, for example “no history: classification awaiting approval”. Absent when the layer ran, or when the run did not report a reason.
Set when the run deliberately did not run this layer for the object, with the reason as the agent reported it, for example “no history: classification awaiting approval”. Absent when the layer ran, or when the run did not report a reason.
started_atstringYesTimestamp when the task started.
Timestamp when the task started.
statusstringYesLifecycle status of the task.
Lifecycle status of the task.
task_idintegerNoUnique identifier of the task.
Unique identifier of the task.
waitingObjectWaitReasonNo

Object Wait Reason  

type: ObjectWaitReason

Why a run loaded an object to staging and stopped there, waiting on its classification. Exactly three values, so a client never parses a skip_reason text. awaiting_approval: a proposed classification waits for a person, because the advisor was unsure. awaiting_rebuild_confirmation: the object’s history already exists on a target in another history mode than the run resolves it to, and a person must confirm a history rebuild (approve or change the classification, or save the job, with rebuild_history); this covers an auto-approval held for a rebuild (held_for_rebuild), and it is the value an agent reports for the run-time refusal (HistoryRebuildConflict). The other history mode is the built mode listHistoryStates lists; an object with none listed on that target never waits with this value: its run adopts the history mode it resolves, reports it, and is not refused. awaiting_classification: there is no classification yet, because the advisor gave no answer (own key failed, allowance used up, no provider, or an outage). A disabled advisor never makes an object wait. Set on a task or an object only when it waits; absent otherwise.

Run Rerun Ref  

type: RunRerunRef

Reference returned when a rerun of failed objects is dispatched: the RunTriggerRef fields plus the commit the rerun runs at.

Child elements:

Run Trigger Ref  

type: RunTriggerRef

Reference returned when a run is dispatched from the control plane.

PropertyTypeRequiredDescription
cmd_idstringYesCorrelation key linking this dispatch to the agent’s run_started telemetry.
Correlation key linking this dispatch to the agent’s run_started telemetry.
statusstringYesqueued | queued_offline
queued | queued_offline

Run Report  

type: RunReport

The report and optional remedy attached to a job run.

PropertyTypeRequiredDescription
remedyobjectNoOptional structured remedy describing how to resolve a failed run.
Optional structured remedy describing how to resolve a failed run.
reportobjectYesStructured report describing the run outcome.
Structured report describing the run outcome.

Run Detail  

type: RunDetail

Projected view of a run’s checkpoint tree for the run-detail viewer (ADR-050/ADR-057).

PropertyTypeRequiredDescription
config_commit_sha[string null]NoFull SHA of the configuration commit the run executed (ADR-129 decisions 1 and 11). Null with config_source draft means the agent did not hold a commit byte for byte. Absent or null with no config_source means unknown: the run was reported by an older agent that does not send its commit. Examples: 8f14e45fceea167a5a36dedd4bea2543c3a6f7b2.
Full SHA of the configuration commit the run executed (ADR-129 decisions 1 and 11). Null with config_source draft means the agent did not hold a commit byte for byte. Absent or null with no config_source means unknown: the run was reported by an older agent that does not send its commit. Examples: 8f14e45fceea167a5a36dedd4bea2543c3a6f7b2.
config_source[string null]NoWhere the run’s configuration came from. commit means the agent held the commit config_commit_sha byte for byte; draft means its configuration was written by a file-form deploy or a local edit, so it matches no commit and config_commit_sha is null. Absent or null means unknown: the run was reported by an older agent, never draft. Valid values are: commit, draft. Examples: commit.
Where the run’s configuration came from. commit means the agent held the commit config_commit_sha byte for byte; draft means its configuration was written by a file-form deploy or a local edit, so it matches no commit and config_commit_sha is null. Absent or null means unknown: the run was reported by an older agent, never draft. Valid values are: commit, draft. Examples: commit.
idstringYesRun identifier (string representation of run_id).
Run identifier (string representation of run_id).
phasesRunPhase []YesOrdered list of run phases projected from the checkpoint tree.
Ordered list of run phases projected from the checkpoint tree.
statusstringYesViewer status of the run. Valid values are: pending, running, done, failed, warning.
Viewer status of the run. Valid values are: pending, running, done, failed, warning.
strategy[string null]NoLoad strategy the run was dispatched with; the strategy actually applied per object is reported on its tasks. null = not reported (older agent or older run). Valid values are: full, incremental, window, full_reload. Examples: incremental.
Load strategy the run was dispatched with; the strategy actually applied per object is reported on its tasks. null = not reported (older agent or older run). Valid values are: full, incremental, window, full_reload. Examples: incremental.

Run Phase  

type: RunPhase

A phase in the run-detail viewer, projected from a root checkpoint’s children.

PropertyTypeRequiredDescription
duration_ms[integer null]NoPhase duration in milliseconds; absent while in progress.
Phase duration in milliseconds; absent while in progress.
error[string null]NoError hint from the first failed checkpoint in the phase; absent on success.
Error hint from the first failed checkpoint in the phase; absent on success.
log_linesstring[]YesDerived log lines for the phase (name + status + duration per descendant checkpoint).
Derived log lines for the phase (name + status + duration per descendant checkpoint).
namestringYesPhase name (from the checkpoint name).
Phase name (from the checkpoint name).
statusstringYesViewer status of the phase. Valid values are: pending, running, done, failed, warning.
Viewer status of the phase. Valid values are: pending, running, done, failed, warning.
tasksRunTask []YesOrdered list of tasks within the phase.
Ordered list of tasks within the phase.

Run Task  

type: RunTask

A task within a phase in the run-detail viewer.

PropertyTypeRequiredDescription
namestringYesTask name (from the checkpoint name).
Task name (from the checkpoint name).
statusstringYesViewer status of the task. Valid values are: pending, running, done, failed, warning.
Viewer status of the task. Valid values are: pending, running, done, failed, warning.

Run Update  

type: RunUpdate

The payload to update a job run.

PropertyTypeRequiredDescription
duration_msintegerNoTotal run duration in milliseconds.
Total run duration in milliseconds.
error_countintegerNoNumber of errors recorded during the run.
Number of errors recorded during the run.
finished_atstringNoTimestamp when the run finished.
Timestamp when the run finished.
statusstringYesNew lifecycle status of the run. Examples: finished.
New lifecycle status of the run. Examples: finished.
tables_failedintegerNoNumber of tables that failed.
Number of tables that failed.
tables_okintegerNoNumber of tables that completed successfully.
Number of tables that completed successfully.
tables_waitingintegerNoNumber of tables the run loaded to staging and then stopped there, waiting on their classification (ObjectWaitReason). Read back as Run.tables_waiting. An agent older than this field omits it.
Number of tables the run loaded to staging and then stopped there, waiting on their classification (ObjectWaitReason). Read back as Run.tables_waiting. An agent older than this field omits it.
total_bytesintegerNoTotal bytes processed across all tasks.
Total bytes processed across all tasks.
total_rowsintegerNoTotal rows processed across all tasks.
Total rows processed across all tasks.
warning_countintegerNoNumber of warnings recorded during the run.
Number of warnings recorded during the run.
Last updated on October 31, 2026

On this page