v1

latestOpenAPI 3.0.02026-08-04891301.4 MB

Retrieve a schedule

Returns a single schedule belonging to the specified agent. Use this endpoint to fetch the current state, next run time, and configuration of an individual schedule.

Requires an app-scoped API key. Both the agent and the schedule must belong to the app identified by the key. Returns 404 if the schedule does not exist or belongs to a different agent.

get/api/v1/agents/{agent}/schedules/{schedule}

Path parameters

agentstring required

Agent ID (agi_...). The agent that owns the schedule.

schedulestring required

Schedule ID (asc_...). The schedule to retrieve.

Response

Successful response

agentstring

ID of the agent that owns this schedule (agi_...).

appstring

ID of the application the schedule belongs to (dap_...).

created_atstring date-time

When the schedule was created (ISO 8601).

cron_expressionstring

Standard cron expression defining the recurrence pattern (e.g. "0 9 * * 1"). Present only when schedule_type is "recurring". null for one-time schedules.

idstring required

Schedule ID (asc_...).

instructionsstring

The task description the agent will execute when this schedule fires.

last_run_atstring date-time

UTC datetime of the most recent successful execution. null if the schedule has never run.

max_runsinteger

Maximum number of times a recurring schedule may fire before automatically transitioning to "completed". null means no limit.

metadataobject

Arbitrary key-value pairs attached to the schedule by the agent. Not interpreted by the platform.

next_run_atstring date-time

UTC datetime of the next planned execution. null if the schedule has completed, been cancelled, or has not yet been computed.

run_countinteger

Total number of times this schedule has fired.

schedule_typestring

Determines how the schedule repeats. "once" fires a single time at scheduled_at then transitions to "completed". "recurring" fires on the cron_expression and reschedules automatically.

scheduled_atstring date-time

The exact UTC datetime at which a one-time schedule fires. Present only when schedule_type is "once". null for recurring schedules.

statusstring

Current lifecycle status of the schedule. One of "active" (will fire as planned), "paused" (temporarily suspended), "completed" (has run its last execution), "cancelled" (manually stopped), or "expired" (past its valid window).

threadstring

Thread ID (thr_...) this schedule is bound to. When set, the scheduled task is delivered into the thread rather than creating a new session. null for session-based schedules.

timezonestring

IANA timezone name used to interpret the cron expression or scheduled_at (e.g. "America/New_York"). Defaults to "Etc/UTC".

updated_atstring date-time

When the schedule was last modified (ISO 8601).

Example response

{
  "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
  "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
  "created_at": "2024-01-01T00:00:00Z",
  "cron_expression": "0 9 * * 1",
  "id": "asc_0aBcDeFgHiJkLmNoPqRsTu",
  "instructions": "Send a daily summary of open support tickets to the team Slack channel.",
  "last_run_at": "2024-01-01T00:00:00Z",
  "max_runs": 10,
  "metadata": {
    "key": "value"
  },
  "next_run_at": "2024-01-01T00:00:00Z",
  "run_count": 1,
  "schedule_type": "recurring",
  "scheduled_at": "2024-01-01T00:00:00Z",
  "status": "active",
  "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu",
  "timezone": "America/New_York",
  "updated_at": "2024-01-01T00:00:00Z"
}