## List Run Schedules

**get** `/agents/{agent_id}/schedules`

List run schedules for an agent.

### Path Parameters

- `agent_id: string`

### Query Parameters

- `include_live: optional boolean`

  Include live Temporal state and upcoming action times.

- `limit: optional number`

### Returns

- `run_schedules: array of object { id, agent_id, initial_input, 20 more }`

  The list of run schedules.

  - `id: string`

    The unique identifier of the run schedule.

  - `agent_id: string`

    The agent this schedule belongs to.

  - `initial_input: object { content, author, type }`

    The initial input.

    - `content: string`

      The initial prompt delivered to the task.

    - `author: optional MessageAuthor`

      The author attributed to the initial input.

      - `"user"`

      - `"agent"`

    - `type: optional "text"`

      Input content type.

      - `"text"`

  - `initial_input_method: string`

    Delivery method, inferred from the agent's ACP type.

  - `name: string`

    Human-readable schedule name.

  - `created_at: optional string`

    When the schedule was created.

  - `creator_principal: optional object { account_id, principal_type, service_account_id, user_id }`

    Credential-free creator identity stored with the schedule.

    Never carries cookies, JWTs, API keys, OAuth tokens, or request headers — it
    is creator *context* used only for AuthZ and ownership at fire time.

    - `account_id: optional string`

      Account/workspace id of the creator.

    - `principal_type: optional string`

      e.g. 'user' or 'service_account'.

    - `service_account_id: optional string`

      Creator service-account id, if a service principal.

    - `user_id: optional string`

      Creator user id, if a user principal.

  - `cron_expression: optional string`

    Cron cadence, if cron-based.

  - `description: optional string`

    Optional description.

  - `end_at: optional string`

    Schedule deactivation time.

  - `interval_seconds: optional number`

    Interval cadence in seconds, if interval-based.

  - `last_action_time: optional string`

    When the schedule last fired.

  - `live_data_available: optional boolean`

    Whether requested live Temporal fields were retrieved successfully. Null when live enrichment was not requested.

  - `next_action_times: optional array of string`

    Upcoming scheduled fire times.

  - `num_actions_taken: optional number`

    Number of times the schedule has fired.

  - `paused: optional boolean`

    Whether the schedule is paused.

  - `skipped_action_times: optional array of string`

    Skipped one-off scheduled fire times.

  - `start_at: optional string`

    Schedule activation time.

  - `state: optional "ACTIVE" or "PAUSED"`

    Live schedule state from Temporal.

    - `"ACTIVE"`

    - `"PAUSED"`

  - `task_metadata: optional map[unknown]`

    Task metadata at fire time.

  - `task_params: optional map[unknown]`

    Task params at fire time.

  - `timezone: optional string`

    Timezone the cron expression is evaluated in.

  - `updated_at: optional string`

    When the schedule was updated.

- `total: number`

  The number of run schedules returned.

### Example

```http
curl http://localhost:5003/agents/$AGENT_ID/schedules \
    -H "Authorization: Bearer $AGENTEX_SDK_API_KEY"
```

#### Response

```json
{
  "run_schedules": [
    {
      "id": "id",
      "agent_id": "agent_id",
      "initial_input": {
        "content": "content",
        "author": "user",
        "type": "text"
      },
      "initial_input_method": "initial_input_method",
      "name": "name",
      "created_at": "2019-12-27T18:11:19.117Z",
      "creator_principal": {
        "account_id": "account_id",
        "principal_type": "principal_type",
        "service_account_id": "service_account_id",
        "user_id": "user_id"
      },
      "cron_expression": "cron_expression",
      "description": "description",
      "end_at": "2019-12-27T18:11:19.117Z",
      "interval_seconds": 0,
      "last_action_time": "2019-12-27T18:11:19.117Z",
      "live_data_available": true,
      "next_action_times": [
        "2019-12-27T18:11:19.117Z"
      ],
      "num_actions_taken": 0,
      "paused": true,
      "skipped_action_times": [
        "2019-12-27T18:11:19.117Z"
      ],
      "start_at": "2019-12-27T18:11:19.117Z",
      "state": "ACTIVE",
      "task_metadata": {
        "foo": "bar"
      },
      "task_params": {
        "foo": "bar"
      },
      "timezone": "timezone",
      "updated_at": "2019-12-27T18:11:19.117Z"
    }
  ],
  "total": 0
}
```