Docs
checkpoint
Lifecycle checkpoints recorded during a job run.
Amfelt REST API · v1.13.0
· https://api.amfelt.com
GET
/v1/telemetry/runs/{run_id}/checkpoints
List run checkpoints.
Returns a page of lifecycle checkpoints for a job run, ordered by start time. Assembling the parent/child tree is the client’s responsibility.Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
X-Tenant-Slug | header | Yes | string | Slug 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_id | path | Yes | integer | Identifier of the job run. |
Identifier of the job run. | ||||
cursor | query | No | string | Opaque 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. | ||||
limit | query | No | integer | Maximum number of items to return per page. |
Maximum number of items to return per page. | ||||
Responses
200
A page of checkpoints.
application/json
| Property | Type | Required | Description |
|---|---|---|---|
data | Checkpoint [] | Yes | The page of checkpoints. |
The page of checkpoints. | |||
next_cursor | [string null] | No | Opaque 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
| Property | Type | Required | Description |
|---|---|---|---|
code | string | Yes | 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. |
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. | |||
field | string | No | 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. |
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. | |||
message | string | Yes | Human-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
| Property | Type | Required | Description |
|---|---|---|---|
code | string | Yes | 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. |
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. | |||
field | string | No | 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. |
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. | |||
message | string | Yes | Human-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/telemetry/runs/{run_id}/checkpoints
Create run checkpoints.
Records one or more lifecycle checkpoints for a job run. The run is identified by the path; any run_id in a checkpoint body is ignored.Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
run_id | path | Yes | integer | Identifier of the job run. |
Identifier of the job run. | ||||
Request body (required)
application/json
Responses
201
The checkpoints were created.
application/json
| Property | Type | Required | Description |
|---|---|---|---|
checkpoint_ids | integer[] | Yes | Server-assigned checkpoint identifiers, in request order. |
Server-assigned checkpoint identifiers, in request order. | |||
400
The request was malformed or failed validation.
application/json
| Property | Type | Required | Description |
|---|---|---|---|
code | string | Yes | 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. |
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. | |||
field | string | No | 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. |
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. | |||
message | string | Yes | Human-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
| Property | Type | Required | Description |
|---|---|---|---|
code | string | Yes | 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. |
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. | |||
field | string | No | 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. |
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. | |||
message | string | Yes | Human-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
Checkpoint List
type: CheckpointList
A page of checkpoints.
| Property | Type | Required | Description |
|---|---|---|---|
data | Checkpoint [] | Yes | The page of checkpoints. |
The page of checkpoints. | |||
next_cursor | [string null] | No | Opaque 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. | |||
Checkpoint
type: Checkpoint
A lifecycle checkpoint recorded during a job run.
| Property | Type | Required | Description |
|---|---|---|---|
attributes | object | No | Arbitrary structured attributes attached to the checkpoint. |
Arbitrary structured attributes attached to the checkpoint. | |||
checkpoint_id | integer | No | Server-assigned identifier of the checkpoint; ignored on create. |
Server-assigned identifier of the checkpoint; ignored on create. | |||
duration_ms | integer | No | Checkpoint duration in milliseconds. |
Checkpoint duration in milliseconds. | |||
ended_at | string | No | Timestamp when the checkpoint ended. |
Timestamp when the checkpoint ended. | |||
error_code | string | No | Optional error code recorded for the checkpoint. |
Optional error code recorded for the checkpoint. | |||
error_hint | string | No | Optional human-readable hint for resolving a checkpoint error. |
Optional human-readable hint for resolving a checkpoint error. | |||
error_retriable | boolean | No | Whether the checkpoint error is retriable. |
Whether the checkpoint error is retriable. | |||
name | string | Yes | Human-readable name of the checkpoint. |
Human-readable name of the checkpoint. | |||
parent_id | integer | No | Identifier of the parent checkpoint; ignored on create. |
Identifier of the parent checkpoint; ignored on create. | |||
parent_ref | string | No | Client-assigned reference of the parent checkpoint; resolved to parent_id on create. |
Client-assigned reference of the parent checkpoint; resolved to parent_id on create. | |||
phase | string | Yes | Lifecycle phase of the checkpoint. Valid values are: job, assignment, preflight, plan, group, task, finalize. Examples: task. |
Lifecycle phase of the checkpoint. Valid values are: job, assignment, preflight, plan, group, task, finalize. Examples: task. | |||
ref | string | No | Client-assigned reference identifying the checkpoint within the run. |
Client-assigned reference identifying the checkpoint within the run. | |||
rerun_scope | string | No | Scope at which a rerun should be triggered. Valid values are: task, group, job. Examples: task. |
Scope at which a rerun should be triggered. Valid values are: task, group, job. Examples: task. | |||
run_id | integer | Yes | Identifier of the run the checkpoint belongs to. |
Identifier of the run the checkpoint belongs to. | |||
started_at | string | Yes | Timestamp when the checkpoint started. |
Timestamp when the checkpoint started. | |||
status | string | Yes | Outcome status of the checkpoint. Valid values are: pending, ok, warn, fail. Examples: ok. |
Outcome status of the checkpoint. Valid values are: pending, ok, warn, fail. Examples: ok. | |||
Error
type: Error
The standard error envelope returned by every non-2xx response.
| Property | Type | Required | Description |
|---|---|---|---|
code | string | Yes | 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. |
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. | |||
field | string | No | 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. |
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. | |||
message | string | Yes | Human-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. | |||
Checkpoint IDS
type: CheckpointIds
The identifiers of the created checkpoints.
| Property | Type | Required | Description |
|---|---|---|---|
checkpoint_ids | integer[] | Yes | Server-assigned checkpoint identifiers, in request order. |
Server-assigned checkpoint identifiers, in request order. | |||
Last updated on October 31, 2026