Skip to content
Embabel Worlds

What an agent will do next

GET
/api/v1/agents/{name}/upcoming
curl --request GET \
  --url http://localhost:11044/api/v1/agents/example/upcoming \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>'

Its scheduled duty checks and routines with when each fires, the requests its last checks say to expect, work in flight, and its recent counts.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
name
required
string

The agent’s name

Responses

Section titled “Responses”

200

Section titled “200”

The agent’s upcoming work

Media typeapplication/json

What an agent will do next: its scheduled firings, the routines that wait for a signal, the requests its last duty checks say to expect, work in flight, and its recent counts. Answered by GET /agents/{name}/upcoming and after a skip or run-now

object
agent
required

Name of the agent, as asked

string
counts
required

What it has done lately, in the units a budget is set in

object
requestsToday
required

Requests it raised today for a person to approve, from the same midnight

integer format: int32
runsLastHour
required

Runs started in the last hour, skipped firings excluded, counted over its 500 most recent runs

integer format: int32
writesToday
required

Changes it made today: receipts where a call acted, plus requests a person approved. Today starts at midnight in the user’s time zone, UTC when they have none

integer format: int32
expected
required

Duties whose next check is expected to raise requests again

Array<object>

A duty whose last check found violations and that declares a repair: the next check will raise its requests again if nothing changes

object
duty
required

Name of the duty

string
lastCheckedAt

ISO-8601 instant of that check

string format: date-time
violations
required

Violations its last check found

integer format: int32
firings
required

Its scheduled duty checks and routines, soonest first, those with no next time last. Only jobs the scheduler holds: a duty whose agent is off duty has none

Array<object>

One of an agent’s scheduled jobs, a duty check or a routine, with when it next fires

object
cron
required

The job’s six-field cron expression, seconds first

string
job
required

Name of the scheduler’s job: the job to send to skip or run-now

string
kind
required

duty or routine

string
nextAt

ISO-8601 instant of its next firing; null when the cron does not parse or its zone cannot be read

string format: date-time
postponedTo

When the skipped firing was postponed rather than dropped, the ISO-8601 instant it runs instead; null otherwise

string format: date-time
skipped
required

True when a person has marked the next firing to be skipped

boolean
work
required

Name of the duty or routine the job runs

string
zone
required

IANA zone id the cron is read in: the job’s own when it declares one, else the user’s (UTC when they have none)

string
inFlight
required

Its runs still in progress, from its 500 most recent

Array<object>

A run of the agent’s still in progress

object
deadline
required

ISO-8601 instant 30 minutes after it started; a run still open past it is closed as timed out

string format: date-time
runId
required

Id of the run, as in GET /agents/{name}/runs/{id}

string
startedAt
required

ISO-8601 instant it started

string format: date-time
work
required

The routine, duty or conversation it is running, as its run records it

string
onSignals
required

Names of the routines it holds that have no scheduled job: the ones that run when something happens rather than at a time

Array<string>

Example generated

{
  "agent": "example",
  "counts": {
    "requestsToday": 1,
    "runsLastHour": 1,
    "writesToday": 1
  },
  "expected": [
    {
      "duty": "example",
      "lastCheckedAt": "2026-04-15T12:00:00Z",
      "violations": 1
    }
  ],
  "firings": [
    {
      "cron": "example",
      "job": "example",
      "kind": "example",
      "nextAt": "2026-04-15T12:00:00Z",
      "postponedTo": "2026-04-15T12:00:00Z",
      "skipped": true,
      "work": "example",
      "zone": "example"
    }
  ],
  "inFlight": [
    {
      "deadline": "2026-04-15T12:00:00Z",
      "runId": "example",
      "startedAt": "2026-04-15T12:00:00Z",
      "work": "example"
    }
  ],
  "onSignals": [
    "example"
  ]
}

401

Section titled “401”

No authenticated principal

One of:

A refusal with a machine-readable code and a plain-language message. ApiErrorAdvice answers it for a failed validation, a missing resource or a conflicting state, and some controllers answer it directly

object
code
required

Machine-readable key to branch on, such as validation_failed, unknown_field, not_found or conflict. Open: a surface may answer codes of its own

string
detail

Extra context where there is some, such as the fields a body may carry; null otherwise

string
message
required

A plain-language explanation, written to be shown. Never carries an exception message

string

Example generated

{
  "code": "example",
  "detail": "example",
  "message": "example"
}