Run one of an agent's scheduled jobs now, outside its schedule
const url = 'http://localhost:11044/api/v1/agents/example/upcoming/run';const options = { method: 'POST', headers: {'X-Embabel-Api-Key': '<X-Embabel-Api-Key>', 'Content-Type': 'application/json'}, body: '{"job":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url http://localhost:11044/api/v1/agents/example/upcoming/run \ --header 'Content-Type: application/json' \ --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \ --data '{ "job": "example" }'Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The agent’s name
Request Bodyrequired
Section titled “Request Bodyrequired”job names one of the agent’s scheduled jobs, as job in its upcoming work; it is started now, outside its schedule, and the run appears on the agent’s runs. 409 when the agent has no such job
One of an agent’s scheduled jobs to run now, outside its schedule; sent to POST /agents/{name}/upcoming/run
object
Name of the scheduled job, as a firing’s job in GET /agents/{name}/upcoming
Example generated
{ "job": "example"}Responses
Section titled “Responses”The upcoming work; the run appears on the agent’s runs
What an agent will do next after a skip or a run-now, or why the change was refused
object
Why the change was refused, in words; null when it was made
The agent’s upcoming work after the change; null when it was refused
object
Name of the agent, as asked
What it has done lately, in the units a budget is set in
object
Requests it raised today for a person to approve, from the same midnight
Runs started in the last hour, skipped firings excluded, counted over its 500 most recent runs
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
Duties whose next check is expected to raise requests again
A duty whose last check found violations and that declares a repair: the next check will raise its requests again if nothing changes
object
Name of the duty
ISO-8601 instant of that check
Violations its last check found
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
One of an agent’s scheduled jobs, a duty check or a routine, with when it next fires
object
The job’s six-field cron expression, seconds first
Name of the scheduler’s job: the job to send to skip or run-now
duty or routine
ISO-8601 instant of its next firing; null when the cron does not parse or its zone cannot be read
When the skipped firing was postponed rather than dropped, the ISO-8601 instant it runs instead; null otherwise
True when a person has marked the next firing to be skipped
Name of the duty or routine the job runs
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)
Its runs still in progress, from its 500 most recent
A run of the agent’s still in progress
object
ISO-8601 instant 30 minutes after it started; a run still open past it is closed as timed out
Id of the run, as in GET /agents/{name}/runs/{id}
ISO-8601 instant it started
The routine, duty or conversation it is running, as its run records it
Names of the routines it holds that have no scheduled job: the ones that run when something happens rather than at a time
Example generated
{ "refused": "example", "upcoming": { "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" ] }}No authenticated principal
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
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
Extra context where there is some, such as the fields a body may carry; null otherwise
A plain-language explanation, written to be shown. Never carries an exception message
The body the servlet error dispatch answers for a status raised by an exception rather than written by the endpoint. Every failure except 404, which answers the not-found HTML page
object
The status’s standard reason phrase, such as Bad Request or Forbidden
The request path that failed
The HTTP status code, repeated from the status line
Example generated
{ "code": "example", "detail": "example", "message": "example"}Refused: the agent has no such scheduled job
What an agent will do next after a skip or a run-now, or why the change was refused
object
Why the change was refused, in words; null when it was made
The agent’s upcoming work after the change; null when it was refused
object
Name of the agent, as asked
What it has done lately, in the units a budget is set in
object
Requests it raised today for a person to approve, from the same midnight
Runs started in the last hour, skipped firings excluded, counted over its 500 most recent runs
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
Duties whose next check is expected to raise requests again
A duty whose last check found violations and that declares a repair: the next check will raise its requests again if nothing changes
object
Name of the duty
ISO-8601 instant of that check
Violations its last check found
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
One of an agent’s scheduled jobs, a duty check or a routine, with when it next fires
object
The job’s six-field cron expression, seconds first
Name of the scheduler’s job: the job to send to skip or run-now
duty or routine
ISO-8601 instant of its next firing; null when the cron does not parse or its zone cannot be read
When the skipped firing was postponed rather than dropped, the ISO-8601 instant it runs instead; null otherwise
True when a person has marked the next firing to be skipped
Name of the duty or routine the job runs
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)
Its runs still in progress, from its 500 most recent
A run of the agent’s still in progress
object
ISO-8601 instant 30 minutes after it started; a run still open past it is closed as timed out
Id of the run, as in GET /agents/{name}/runs/{id}
ISO-8601 instant it started
The routine, duty or conversation it is running, as its run records it
Names of the routines it holds that have no scheduled job: the ones that run when something happens rather than at a time
Example generated
{ "refused": "example", "upcoming": { "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" ] }}