Docs
telemetry
Agent telemetry firehose. Agents POST run/task lifecycle events to feed the in-memory ring buffer that backs the live SSE stream; admins can purge the cache to reclaim memory.
Amfelt REST API · v1.13.0
· https://api.amfelt.com
POST
/v1/telemetry/events
Ingest agent telemetry events.
Agents post a batch of run and task lifecycle events. Each event’s agent_id (if set) must match the JWT-derived agent id. Events feed the in-memory ring buffer that backs the live SSE stream and the persister write-through that populates core.run and core.task.Request body (required)
application/json
| Property | Type | Required | Description |
|---|---|---|---|
data | TelemetryEvent [] | Yes | The batch of events. |
The batch of events. | |||
Responses
204
Events were accepted.
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. | |||
403
The caller is authenticated but not permitted to perform the request.
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
DELETE
/v1/telemetry/events
Purge the telemetry cache.
Empties the in-memory ring buffer for the caller’s organization. Durable run history in core.run is unaffected. Intended for management-console operators who need to reclaim memory after a load test or replay window.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. | ||||
Responses
204
The cache was purged.
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. | |||
403
The caller is authenticated but not permitted to perform the request.
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
Telemetry Event List
type: TelemetryEventList
Request-body envelope for POST /v1/telemetry/events. Carries a batch of events; no cursor field because writes are not paginated.
| Property | Type | Required | Description |
|---|---|---|---|
data | TelemetryEvent [] | Yes | The batch of events. |
The batch of events. | |||
Telemetry Event
type: TelemetryEvent
A single agent-emitted run or task lifecycle event. event_type is a free string validated server-side against a closed set; the set evolves with agent capabilities and is intentionally not enumerated in the spec.
| Property | Type | Required | Description |
|---|---|---|---|
agent_id | string | No | Identifier of the emitting agent. When set the server cross-checks against the JWT-derived agent id and rejects mismatches. |
Identifier of the emitting agent. When set the server cross-checks against the JWT-derived agent id and rejects mismatches. | |||
event_type | string | Yes | The kind of event recorded (e.g. run_started, task_progress, checkpoint, plugin_ready). Examples: task_progress. |
The kind of event recorded (e.g. run_started, task_progress, checkpoint, plugin_ready). Examples: task_progress. | |||
job_name | string | No | Job name as reported by the agent. |
Job name as reported by the agent. | |||
payload | object | No | Free-form per-event payload; shape depends on event_type. With event_type run_finished it is a RunUpdate, and with task_finished a TaskUpdate, so the agent and the api agree on those two inside this contract. Other event types’ payloads are not described here. |
Free-form per-event payload; shape depends on event_type. With event_type run_finished it is a RunUpdate, and with task_finished a TaskUpdate, so the agent and the api agree on those two inside this contract. Other event types’ payloads are not described here. | |||
run_id | integer | Yes | Identifier of the run the event belongs to. |
Identifier of the run the event belongs to. | |||
timestamp | string | No | Event timestamp as reported by the agent. Falls back to the server clock when absent or unparseable. |
Event timestamp as reported by the agent. Falls back to the server clock when absent or unparseable. | |||
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. | |||
Last updated on October 31, 2026