> ## Documentation Index > Fetch the complete documentation index at: https://docs.guidinghand.ai/llms.txt > Use this file to discover all available pages before exploring further. # List an agent’s schedules ## OpenAPI ````yaml /api-reference/openapi.json get /v1/agents/{agent_id}/schedules openapi: 3.1.0 info: title: Eager API version: 1.0.0 description: >- Train AI agents like new hires: hand an agent your files and coach it, and it writes its own procedures and works in any software, even without an API. Talk to your agents one message at a time (POST /v1/agents/{agent_id}/responses): they answer from their files, procedures and your HTTP tools, and run tasks on their own cloud browser or your linked computers when an answer needs a website or a desktop app. Manage agents (versioned: save a draft, publish it), their procedures, browser and computers; follow conversations and tasks, answer approvals, and fetch history and recordings. Run tasks yourself on a session: a customer’s computer through an invite link, or a cloud browser. Test agents with evals: chat, browser and desktop test cases, run several times against your agents and judged on the answer. Every change is in the org’s audit log. servers: - url: https://guidinghand.ai description: Production - url: https://dev.guidinghand.ai description: Development (Stripe test mode) security: - bearerAuth: [] tags: - name: Agents - name: Agent files - name: Agent tools - name: Agent folders - name: Computers description: >- Computers your org links with the Eager app, and pools of them, for agents’ desktop tasks. Attach them to an agent in its `resources.computers`. - name: Phone numbers description: >- Bring your own Twilio numbers: connect the account, add its numbers, and pick the agent that answers each. Calls are answered by the agent's published version. - name: Sessions - name: Tasks - name: Webhooks - name: Audit log - name: Test cases - name: Test sets - name: Test runs - name: Start states - name: Runners - name: Responses description: >- Talk to an agent: each call is one turn of a conversation. The agent answers with its files, procedures and tools (and, with Run code, its own sandbox), asks for details with forms, and runs browser and desktop tasks when an answer needs a website or a desktop app. - name: Conversations description: >- The history of each conversation: messages, tool calls and the tasks the agent started, in order. - name: Uploads description: >- Files for conversations: attach them to a message, and download what the agent’s code made. Kept as long as their conversation. - name: Procedures description: >- An agent’s playbooks: when to use each and its steps. The agent finds and follows them; ones it writes from a first run are marked written_by: agent. - name: Categories description: The kinds of request an org’s procedures and test cases are sorted into. - name: Escalations description: >- What needs your team: an approval only the team can give or a question only it can answer, in a real conversation; a procedure run that failed; and one that worked another way, with the procedure rewritten to match (a proposed change). Test chats never escalate; evals do, without webhooks. - name: Schedules description: >- Run an agent’s procedure on a cron expression, in a time zone, with the inputs it needs. Each run is a conversation of its own with nobody in it (`channel` `schedule` in its variables): the procedure’s steps without AI run outright when it has them, else the model follows it to its end. Its record says how it ended, what the agent said last and what it cost; the team hears by webhook (`schedule.run_completed`, `schedule.run_failed`), email and Slack or Teams, as the schedule says. paths: /v1/agents/{agent_id}/schedules: parameters: - name: agent_id in: path required: true description: The agent’s id. schema: type: string get: tags: - Schedules summary: List an agent’s schedules operationId: listSchedules parameters: - name: procedure_id in: query required: false schema: type: string - name: status in: query required: false schema: type: string enum: - active - paused responses: '200': description: The list. content: application/json: schema: type: object properties: object: const: list data: type: array items: $ref: '#/components/schemas/Schedule' has_more: type: boolean next_cursor: type: - string - 'null' limits: type: object description: The org’s limits. properties: schedules: type: integer description: Schedules it can have. used: type: integer min_minutes: type: integer description: The shortest gap between runs. runs_at_once: type: integer description: Runs going at once; more are skipped. '404': description: No agent by that id. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: Schedule: type: object description: An agent’s procedure, run on a cron expression in a time zone. properties: object: const: schedule id: type: string example: sch_8c1e2f3a4b5c6d7e8f agent_id: type: string procedure_id: type: string procedure: type: - object - 'null' properties: id: type: string title: type: string kind: type: string status: type: string name: type: string example: Morning warranty check cron: type: string example: 0 9 * * 1-5 description: >- Minute, hour, day of the month, month, day of the week. `*`, ranges, steps, lists and names (MON, JAN); `@hourly`, `@daily`, `@weekly`, `@monthly`, `@yearly`. time_zone: type: string example: America/New_York description: type: string example: Every weekday at 09:00 inputs: type: object additionalProperties: type: string description: >- The procedure’s inputs (and any other values), as the run’s conversation variables. notify: $ref: '#/components/schemas/ScheduleNotify' status: type: string enum: - active - paused next_run_at: type: - string - 'null' format: date-time description: Null while paused. last_run: oneOf: - $ref: '#/components/schemas/ScheduleRun' - type: 'null' created_by: $ref: '#/components/schemas/Actor' created_at: type: string format: date-time updated_at: type: string format: date-time required: - object - id - agent_id - procedure_id - name - cron - time_zone - description - inputs - notify - status Error: type: object required: - error properties: error: type: object required: - type - message properties: type: type: string enum: - invalid_request - authentication - payment_required - permission - not_found - conflict - rate_limit - server_error message: type: string code: type: string description: >- Why it was refused, when there’s more to say than the status. Starting a task or a chat reply: `insufficient_balance`, `auto_topup_limit_reached` or `card_needs_attention` (402: the balance is empty and auto top-up can’t add funds; add funds, raise the auto top-up limit, or update the card), `concurrency_limit` (429), `model_unavailable` (503: the agent’s `model` can’t run on this server; choose another). Deciding a conversation’s request: `already_decided` (409: someone decided or answered it first; see `decided_by`) or `not_pending` (409: its task has ended, so nothing would act on it). POST /v1/tasks/{task_id}/respond: `decide_in_conversation` (409: decide it in the task’s conversation; see `conversation_id`, `agent_id`, and `approval_id` or `question_id`). Deleting a start state that test cases use: `in_use` (409, with `test_case_ids`). test_case_ids: type: array items: type: string description: 'With `in_use`: the test cases that use the start state.' decided_by: description: 'With `already_decided`: who decided first.' allOf: - $ref: '#/components/schemas/Decider' conversation_id: type: string description: >- With `decide_in_conversation`: the conversation to decide it in (POST /v1/conversations/{conversation_id}/decisions). agent_id: type: - string - 'null' description: >- With `decide_in_conversation`: the task’s agent (null for a task run without one). approval_id: type: string description: 'With `decide_in_conversation`: the approval to decide.' question_id: type: string description: 'With `decide_in_conversation`: the question to answer.' ScheduleNotify: type: object description: >- Who hears when a run ends. The org’s webhook always gets `schedule.run_completed` or `schedule.run_failed`. properties: 'on': type: string enum: - always - failure - never default: failure description: >- When to email and post: every run, failed and stopped ones, or never. emails: type: array items: type: string format: email maxItems: 10 description: Org members to email. chat_apps: type: boolean default: false description: >- Post in the channel each linked Slack or Teams workspace takes escalations in. ScheduleRun: type: object description: One run of a schedule, or a slot it skipped or missed. properties: object: const: schedule_run id: type: string example: srun_3f9a0c1b2d4e5f6a7b schedule_id: type: string trigger: type: string enum: - schedule - manual description: '`schedule`: on time; `manual`: run now.' status: type: string enum: - running - waiting - completed - failed - stopped - skipped - missed description: >- `waiting`: on the team’s decision (an approval or a question in its conversation). `skipped`: its last run was still going, or the org had its most runs going at once. `missed`: no server was up when it was due, and it was over an hour late. due_at: type: string format: date-time started_at: type: - string - 'null' format: date-time ended_at: type: - string - 'null' format: date-time conversation_id: type: - string - 'null' description: 'The run’s conversation: everything it said and did.' result: type: - string - 'null' description: What the agent said last. error: type: - string - 'null' escalations: type: integer description: Escalations it raised. cost_cents: type: - number - 'null' description: What its replies and tasks came to, at list price. required: - object - id - schedule_id - trigger - status - due_at Actor: oneOf: - title: Person type: object description: A person in the org (in the console). properties: type: const: user email: type: - string - 'null' example: jane@acme.com - title: API key type: object description: One of the org’s API keys. properties: type: const: api_key key_id: type: string name: type: - string - 'null' example: Zendesk prefix: type: - string - 'null' description: The key’s first characters. example: gh_live_AbC1 - type: 'null' description: >- Who did it: a person (in the console) or an API key. Null when nobody was recorded: it was made with a session token, by Eager itself, or before this was kept. Decider: type: object description: Who decided a request, or answered a question. required: - type properties: type: type: string enum: - person - team - auto - refused - timeout - operator - moved_on description: >- `person`: the person in the chat (in the Eager app, or a visitor to your website’s widget), when the agent lets them (`customer_approvals`, `customer_answers`) and the request isn’t for your team only. `team`: a member in the console (`email`) or an API key (`key_id`). `auto`: the agent’s guardrails approve without asking (`mode: auto`). `refused`: its guardrails refuse (`mode: unattended`). `timeout`: nobody decided within its `approval_timeout_minutes`. `operator`: an eval case’s operator. `moved_on`: the person sent a new message instead, so it was declined. email: type: string description: '`team`: the member who decided.' key_id: type: string description: '`team`: the API key that decided.' securitySchemes: bearerAuth: type: http scheme: bearer description: An org API key (`gh_live_…`) from Settings → API keys in the console. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.