Reconcile and read a durable observer

GET

/v1/agent-tasks/{id}

• Production
• Local

Requires the original agent key or a valid token for the same connection grant. Token exchange and refresh do not change task ownership. Current scopes, role, resource reach, capability profile and the original selection are checked even for cached terminal results. Query overrides are rejected. Unknown, expired or other-owner handles return 404. No action is acknowledged.

Authorizations

• AgentKey

Parameters

Path Parameters

id

required

string

Responses

200

Current observer status with immutable result when completed.

Durable observer bound to the exact connection grant or agent key and its immutable capability profile and selection. Each request rechecks current access. Completion means an observation is available, not that an account was verified or email was sent. Terminal results are immutable. Up to 100 unexpired handles, including completed handles, are retained per owner.

object

id

required

string

kind

required

string

Allowed values: activation review

status

required

string

Allowed values: working completed cancelled

created_at

required

string format: date-time

last_updated_at

required

string format: date-time

expires_at

required

string format: date-time

poll_interval_ms

required

Suggested status-poll interval in milliseconds; normal polling needs no model invocation.

integer

>= 1

result

One of:

object

object

agent_id

required

string

address

required

string format: email

human_email

required

string format: email

created_ms

required

integer format: int64

expires_ms

required

integer format: int64

revision

required

integer format: int64

state

required

string

Allowed values: pending proven activated expired

object

Durable attention for reviews the caller may access, including feedback and rule/category changes. Omit review_id for one shared wait. Reconnect with the same identity to replay unhandled events; waiting never acknowledges work. Events are FIFO per review, with persisted cursors. Delegated observations survive composer acknowledgements.

object

pending_reviews

Remaining active reviews within this wait’s authorized resource and optional review_id boundary; legacy keys retain their composer ceiling. Included on an empty wait.

integer

events

required

Array<object>

One durable review nudge (ndg_…) as drained from the authoritative liveness queue (spec §11). seq is the per-review monotonic ordinal the ack cursor advances against (0 for a broadcast nudge). Opaque typed ids only (D10).

object

seq

required

integer

id

required

string

reason

required

The work-item kind. sent / send_failed / cancelled are TERMINAL: the LAST event a review ever produces is one of these; ack it and stop polling that review. (Almost every review emits exactly one; a failed send the agent then closes out emits send_failed and then cancelled.) sent covers both delivery flavors; payload.state distinguishes sent from auto_sent. approved and staleness are RESERVED and never emitted (kept so the enum is never narrowed). Treat an unrecognized reason as ack-and-ignore: this enum is additive across 0.x releases.

string

Allowed values: redraft_requested feedback_added recheck_category staleness approved rejected front_run_next rule_changed propagate_general_rule sent send_failed cancelled

review_id

string

category_id

string

payload

object

key

additional properties

any

created_at

required

string format: date-time

cursors

Array<object>

The agent’s per-(agent, review) ack frontier; its strict-FIFO position for one review.

object

review_id

required

string

last_acked_seq

required

integer

400

Invalid request.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean

401

Missing or invalid credential.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean

403

Authenticated but lacking the required scope, or out of quota.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean

404

Resource not found.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean