# Schedules

Schedules and their run history.



{/* Generated from openapi/openapi.yaml by `npm run gen:api-docs`. Do not edit by hand. */}

<ApiEndpoint>
  <ApiEndpointMain>
    ## List schedules [#list-schedules]

    <ApiEndpointHeader method="GET" path="/v1/schedules" scope="schedules:read" />

    <ApiParams title="Query parameters">
      <ApiParam name="limit" type="integer">
        How many objects to return, 1 to 100. Default 20.
      </ApiParam>

      <ApiParam name="starting_after" type="string">
        Return objects older than this id (the next page).
      </ApiParam>

      <ApiParam name="ending_before" type="string">
        Return objects newer than this id (the previous page).
      </ApiParam>

      <ApiParam name="team" type="string">
        Only schedules of this AI team.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a list of [Schedule](#schedule) objects.

    <ApiParams title="Responses">
      <ApiParam name="200">
        A page of schedules.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/schedules \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/schedules', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/schedules",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "list",
      "data": [
        {
          "object": "schedule",
          "id": "sched_lCh70bFOv9IaUYUWyFgTif",
          "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
          "name": "Monday market brief",
          "enabled": true,
          "cron": "0 8 * * 1",
          "timezone": "Europe/London",
          "frequency": "weekly",
          "run_times": ["08:00"],
          "prompt": "Summarise the competitor news of the last 7 days into reports/weekly.md.",
          "target_session": null,
          "create_new_session": true,
          "on_stopped_session": "restart",
          "run_with": "team_key",
          "engine": "claude",
          "last_run_at": "2026-10-12T07:00:00.000Z",
          "last_run_status": "success",
          "next_run_at": "2026-10-19T07:00:00.000Z",
          "created_at": "2026-09-21T13:44:09.000Z",
          "created_by": {
            "id": "user_yFfQdB3rxA41x3cTD5fx2Q",
            "name": "Maya Chen"
          }
        }
      ],
      "has_more": false
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Create a schedule [#create-a-schedule]

    <ApiEndpointHeader method="POST" path="/v1/schedules" scope="schedules:write" />

    A schedule runs as the member the user key acts as (a service key cannot create one yet).
    Pointing it at a session that runs on someone else's personal login is refused. Never a
    prompt that would run as a command: see `prompt` for what is refused.

    Schedules always continue the session's conversation so Claude keeps its context. Resuming
    a long conversation uses part of your Claude usage limit.

    On an AI team that turned on Protected files, a Codex schedule needs `files:protected.read` and `files:protected.write` on the key and its person: 403 `protected_files_shell` otherwise.

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Body parameters">
      <ApiParam name="team" type="string" required="true" />

      <ApiParam name="name" type="string" required="true" />

      <ApiParam name="prompt" type="string" required="true">
        The task, as you would type it. Refused with `422 validation_failed` (the reason is in
        `detail`) when it starts with `/`, `!` or `#` (a command, not a task), when it contains a
        control character (tabs and line breaks are fine), or when it contains `kr-run:`, which
        HQ reserves for its own run marker.
      </ApiParam>

      <ApiParam name="timezone" type="string" required="true">
        An IANA time zone, for example Europe/London.
      </ApiParam>

      <ApiParam name="frequency" type="string" required="true">
        One of `daily`, `specific_days`, `weekly`, `monthly`, `once`.
      </ApiParam>

      <ApiParam name="days_of_week" type="array of integer" />

      <ApiParam name="day_of_month" type="integer" />

      <ApiParam name="date" type="string (date)">
        For `once`.
      </ApiParam>

      <ApiParam name="run_time" type="string" required="true">
        HH:mm.
      </ApiParam>

      <ApiParam name="run_times" type="array of string" />

      <ApiParam name="target_session" type="string">
        Run in this existing session. Send exactly one of target_session or create_new_session true.
      </ApiParam>

      <ApiParam name="create_new_session" type="boolean">
        Start a new session for each run. Send exactly one of target_session or create_new_session true.
      </ApiParam>

      <ApiParam name="on_stopped_session" type="string">
        One of `restart`, `skip_notify`.
      </ApiParam>

      <ApiParam name="run_with" type="string">
        With create_new_session only. One of `personal`, `team_key`.
      </ApiParam>

      <ApiParam name="engine" type="string">
        One of `claude`, `codex`.
      </ApiParam>

      <ApiParam name="enabled" type="boolean" />
    </ApiParams>

    **Returns** a [Schedule](#schedule) object.

    <ApiParams title="Responses">
      <ApiParam name="201">
        The schedule.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://api-hq.aiworkforceone.com/v1/schedules \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{
            "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
            "name": "Monday market brief",
            "prompt": "Summarise the competitor news of the last 7 days into reports/weekly.md.",
            "timezone": "Europe/London",
            "frequency": "weekly",
            "run_time": "08:00"
          }'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/schedules', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            team: 'team_3kQ9vX2mR8tLpZ4wYc1aBd',
            name: 'Monday market brief',
            prompt: 'Summarise the competitor news of the last 7 days into reports/weekly.md.',
            timezone: 'Europe/London',
            frequency: 'weekly',
            run_time: '08:00',
          }),
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.post(
            "https://api-hq.aiworkforceone.com/v1/schedules",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            json={
                "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
                "name": "Monday market brief",
                "prompt": "Summarise the competitor news of the last 7 days into reports/weekly.md.",
                "timezone": "Europe/London",
                "frequency": "weekly",
                "run_time": "08:00",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 201"
    {
      "object": "schedule",
      "id": "sched_lCh70bFOv9IaUYUWyFgTif",
      "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
      "name": "Monday market brief",
      "enabled": true,
      "cron": "0 8 * * 1",
      "timezone": "Europe/London",
      "frequency": "weekly",
      "run_times": ["08:00"],
      "prompt": "Summarise the competitor news of the last 7 days into reports/weekly.md.",
      "target_session": null,
      "create_new_session": true,
      "on_stopped_session": "restart",
      "run_with": "team_key",
      "engine": "claude",
      "last_run_at": "2026-10-12T07:00:00.000Z",
      "last_run_status": "success",
      "next_run_at": "2026-10-19T07:00:00.000Z",
      "created_at": "2026-09-21T13:44:09.000Z",
      "created_by": {
        "id": "user_yFfQdB3rxA41x3cTD5fx2Q",
        "name": "Maya Chen"
      }
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Get a schedule [#get-a-schedule]

    <ApiEndpointHeader method="GET" path="/v1/schedules/{schedule_id}" scope="schedules:read" />

    <ApiParams title="Path parameters">
      <ApiParam name="schedule_id" type="string" required="true">
        A schedule id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a [Schedule](#schedule) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The schedule.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "schedule",
      "id": "sched_lCh70bFOv9IaUYUWyFgTif",
      "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
      "name": "Monday market brief",
      "enabled": true,
      "cron": "0 8 * * 1",
      "timezone": "Europe/London",
      "frequency": "weekly",
      "run_times": ["08:00"],
      "prompt": "Summarise the competitor news of the last 7 days into reports/weekly.md.",
      "target_session": null,
      "create_new_session": true,
      "on_stopped_session": "restart",
      "run_with": "team_key",
      "engine": "claude",
      "last_run_at": "2026-10-12T07:00:00.000Z",
      "last_run_status": "success",
      "next_run_at": "2026-10-19T07:00:00.000Z",
      "created_at": "2026-09-21T13:44:09.000Z",
      "created_by": {
        "id": "user_yFfQdB3rxA41x3cTD5fx2Q",
        "name": "Maya Chen"
      }
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Update a schedule [#update-a-schedule]

    <ApiEndpointHeader method="PATCH" path="/v1/schedules/{schedule_id}" scope="schedules:write" />

    Any of the create fields but the team. A user key only.
    On an AI team that turned on Protected files, a Codex schedule's edit needs `files:protected.read` and `files:protected.write` on the key and its person: 403 `protected_files_shell` otherwise.

    <ApiParams title="Path parameters">
      <ApiParam name="schedule_id" type="string" required="true">
        A schedule id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Body parameters">
      <ApiParam name="name" type="string" />

      <ApiParam name="prompt" type="string">
        The same rules as on create.
      </ApiParam>

      <ApiParam name="timezone" type="string" />

      <ApiParam name="frequency" type="string">
        One of `daily`, `specific_days`, `weekly`, `monthly`, `once`.
      </ApiParam>

      <ApiParam name="days_of_week" type="array of integer" />

      <ApiParam name="day_of_month" type="integer" />

      <ApiParam name="date" type="string" />

      <ApiParam name="run_time" type="string" />

      <ApiParam name="run_times" type="array of string" />

      <ApiParam name="target_session" type="string">
        Switches the schedule to run in this existing session (turns create_new_session off).
      </ApiParam>

      <ApiParam name="create_new_session" type="boolean">
        true switches the schedule to a new session for each run (clears target_session).
      </ApiParam>

      <ApiParam name="on_stopped_session" type="string">
        One of `restart`, `skip_notify`.
      </ApiParam>

      <ApiParam name="run_with" type="string">
        One of `personal`, `team_key`.
      </ApiParam>

      <ApiParam name="engine" type="string">
        One of `claude`, `codex`.
      </ApiParam>

      <ApiParam name="enabled" type="boolean" />
    </ApiParams>

    **Returns** a [Schedule](#schedule) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The schedule.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X PATCH https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)" \
          -H "Content-Type: application/json" \
          -d '{"run_time":"09:30","enabled":true}'
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif', {
          method: 'PATCH',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ run_time: '09:30', enabled: true }),
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.patch(
            "https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
            json={"run_time": "09:30", "enabled": True},
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "schedule",
      "id": "sched_lCh70bFOv9IaUYUWyFgTif",
      "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
      "name": "Monday market brief",
      "enabled": true,
      "cron": "0 8 * * 1",
      "timezone": "Europe/London",
      "frequency": "weekly",
      "run_times": ["08:00"],
      "prompt": "Summarise the competitor news of the last 7 days into reports/weekly.md.",
      "target_session": null,
      "create_new_session": true,
      "on_stopped_session": "restart",
      "run_with": "team_key",
      "engine": "claude",
      "last_run_at": "2026-10-12T07:00:00.000Z",
      "last_run_status": "success",
      "next_run_at": "2026-10-19T07:00:00.000Z",
      "created_at": "2026-09-21T13:44:09.000Z",
      "created_by": {
        "id": "user_yFfQdB3rxA41x3cTD5fx2Q",
        "name": "Maya Chen"
      }
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Delete a schedule [#delete-a-schedule]

    <ApiEndpointHeader method="DELETE" path="/v1/schedules/{schedule_id}" scope="schedules:write" />

    <ApiParams title="Path parameters">
      <ApiParam name="schedule_id" type="string" required="true">
        A schedule id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Responses">
      <ApiParam name="204">
        Deleted.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X DELETE https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif', {
          method: 'DELETE',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
          },
        });
        console.log(res.status);
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.delete(
            "https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
        )
        print(res.status_code)
        ```
      </Tab>
    </Tabs>

    <ApiResponseNote status="204">
      Deleted.
    </ApiResponseNote>
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## List a schedule's runs [#list-a-schedules-runs]

    <ApiEndpointHeader method="GET" path="/v1/schedules/{schedule_id}/runs" scope="schedules:read" />

    Newest first. Pages forward with `starting_after`.

    <ApiParams title="Path parameters">
      <ApiParam name="schedule_id" type="string" required="true">
        A schedule id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Query parameters">
      <ApiParam name="limit" type="integer">
        How many objects to return, 1 to 100. Default 20.
      </ApiParam>

      <ApiParam name="starting_after" type="string">
        Return objects older than this id (the next page).
      </ApiParam>

      <ApiParam name="result" type="string">
        Only runs with this result. One of `success`, `failed`, `skipped`.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a list of [ScheduleRun](#schedulerun) objects.

    <ApiParams title="Responses">
      <ApiParam name="200">
        A page of runs.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/runs \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/runs', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/runs",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "list",
      "data": [
        {
          "object": "schedule_run",
          "id": "run_4K76tZDj56MBIaHaI02P1e",
          "schedule": "sched_lCh70bFOv9IaUYUWyFgTif",
          "session": "sess_U9qrDsTXdBGkZFRLFNOCaR",
          "status": "success",
          "outcome": "proven",
          "started_at": "2026-10-12T07:00:02.000Z",
          "completed_at": "2026-10-12T07:06:48.000Z",
          "tokens_used": 40210,
          "cost_usd": 0.58,
          "triggered_by": {
            "id": "user_yFfQdB3rxA41x3cTD5fx2Q",
            "name": "Maya Chen"
          }
        }
      ],
      "has_more": false
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Run a schedule now [#run-a-schedule-now]

    <ApiEndpointHeader method="POST" path="/v1/schedules/{schedule_id}/runs" scope="schedules:run" />

    Fires the schedule's stored prompt now. 202 with the run once it exists (it continues on its
    own), or `queued: true` when the plan queues runs while every session slot is busy; 409
    naming why a run was skipped. Requires an `Idempotency-Key`.
    On an AI team that turned on Protected files, a Codex run needs `files:protected.read` and `files:protected.write` on the key and its person: 403 `protected_files_shell` otherwise. A Codex run whose schedule's author lacks them is skipped: 409 `protected_files_shell`.

    <ApiParams title="Path parameters">
      <ApiParam name="schedule_id" type="string" required="true">
        A schedule id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string" required="true">
        Required here. The same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422; while the first
        request is still running, 409 `idempotency_in_progress`.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a [ScheduleRunRequest](#schedulerunrequest) object.

    <ApiParams title="Responses">
      <ApiParam name="202">
        The run started, or was queued.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/runs \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/runs', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.post(
            "https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/runs",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 202"
    {
      "object": "schedule_run_request",
      "queued": true,
      "run": "run_4K76tZDj56MBIaHaI02P1e",
      "session": null
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Get a schedule run [#get-a-schedule-run]

    <ApiEndpointHeader method="GET" path="/v1/schedules/{schedule_id}/runs/{run_id}" scope="schedules:read" />

    <ApiParams title="Path parameters">
      <ApiParam name="schedule_id" type="string" required="true">
        A schedule id.
      </ApiParam>

      <ApiParam name="run_id" type="string" required="true">
        A schedule run id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a [ScheduleRun](#schedulerun) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The run.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/runs/run_4K76tZDj56MBIaHaI02P1e \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/runs/run_4K76tZDj56MBIaHaI02P1e', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/runs/run_4K76tZDj56MBIaHaI02P1e",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "schedule_run",
      "id": "run_4K76tZDj56MBIaHaI02P1e",
      "schedule": "sched_lCh70bFOv9IaUYUWyFgTif",
      "session": "sess_U9qrDsTXdBGkZFRLFNOCaR",
      "status": "success",
      "outcome": "proven",
      "started_at": "2026-10-12T07:00:02.000Z",
      "completed_at": "2026-10-12T07:06:48.000Z",
      "tokens_used": 40210,
      "cost_usd": 0.58,
      "triggered_by": {
        "id": "user_yFfQdB3rxA41x3cTD5fx2Q",
        "name": "Maya Chen"
      }
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Enable a schedule [#enable-a-schedule]

    <ApiEndpointHeader method="POST" path="/v1/schedules/{schedule_id}/enable" scope="schedules:write" />

    On an AI team that turned on Protected files, a Codex schedule needs `files:protected.read` and `files:protected.write` on the key and its person: 403 `protected_files_shell` otherwise.

    <ApiParams title="Path parameters">
      <ApiParam name="schedule_id" type="string" required="true">
        A schedule id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a [Schedule](#schedule) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The schedule, enabled.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/enable \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/enable', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.post(
            "https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/enable",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "schedule",
      "id": "sched_lCh70bFOv9IaUYUWyFgTif",
      "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
      "name": "Monday market brief",
      "enabled": true,
      "cron": "0 8 * * 1",
      "timezone": "Europe/London",
      "frequency": "weekly",
      "run_times": ["08:00"],
      "prompt": "Summarise the competitor news of the last 7 days into reports/weekly.md.",
      "target_session": null,
      "create_new_session": true,
      "on_stopped_session": "restart",
      "run_with": "team_key",
      "engine": "claude",
      "last_run_at": "2026-10-12T07:00:00.000Z",
      "last_run_status": "success",
      "next_run_at": "2026-10-19T07:00:00.000Z",
      "created_at": "2026-09-21T13:44:09.000Z",
      "created_by": {
        "id": "user_yFfQdB3rxA41x3cTD5fx2Q",
        "name": "Maya Chen"
      }
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Disable a schedule [#disable-a-schedule]

    <ApiEndpointHeader method="POST" path="/v1/schedules/{schedule_id}/disable" scope="schedules:write" />

    <ApiParams title="Path parameters">
      <ApiParam name="schedule_id" type="string" required="true">
        A schedule id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a [Schedule](#schedule) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The schedule, disabled.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/disable \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/disable', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.post(
            "https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/disable",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "schedule",
      "id": "sched_lCh70bFOv9IaUYUWyFgTif",
      "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
      "name": "Monday market brief",
      "enabled": true,
      "cron": "0 8 * * 1",
      "timezone": "Europe/London",
      "frequency": "weekly",
      "run_times": ["08:00"],
      "prompt": "Summarise the competitor news of the last 7 days into reports/weekly.md.",
      "target_session": null,
      "create_new_session": true,
      "on_stopped_session": "restart",
      "run_with": "team_key",
      "engine": "claude",
      "last_run_at": "2026-10-12T07:00:00.000Z",
      "last_run_status": "success",
      "next_run_at": "2026-10-19T07:00:00.000Z",
      "created_at": "2026-09-21T13:44:09.000Z",
      "created_by": {
        "id": "user_yFfQdB3rxA41x3cTD5fx2Q",
        "name": "Maya Chen"
      }
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Move a schedule to its session's owner [#move-a-schedule-to-its-sessions-owner]

    <ApiEndpointHeader method="POST" path="/v1/schedules/{schedule_id}/move_to_session_owner" scope="schedules:write" />

    A schedule that reuses a session runs on the Claude login of the person it runs as
    (`created_by`). When the session is reassigned to someone else, the schedule stops
    running until it is moved. This moves it to the session's current owner: from then on it
    runs on their Claude login, and `created_by` names them.

    It only ever moves to the session's current owner, so it takes no body. Over the API only
    the session's owner can do this, with their own user key: it puts the schedule on their
    own Claude login. Organization owners and admins and team owners move a teammate's
    schedule in HQ. A schedule that already runs as the owner is returned unchanged (safe to
    retry). Schedules that start a new session each run, and schedules on the team's API key,
    cannot be moved, and a schedule never moves to an owner who can't manage schedules on the
    team (`409 owner_cannot_manage_schedules`).

    <ApiParams title="Path parameters">
      <ApiParam name="schedule_id" type="string" required="true">
        A schedule id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="Idempotency-Key" type="string">
        Makes a retry safe: the same key and body within 24 hours returns the first response again
        (`Idempotent-Replayed: true`); the same key with another body is 422.
      </ApiParam>

      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a [Schedule](#schedule) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The schedule, now running as the session's owner.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl -X POST https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/move_to_session_owner \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01" \
          -H "Idempotency-Key: $(uuidgen)"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/move_to_session_owner', {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
            'Idempotency-Key': crypto.randomUUID(),
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os
        import uuid

        import requests

        res = requests.post(
            "https://api-hq.aiworkforceone.com/v1/schedules/sched_lCh70bFOv9IaUYUWyFgTif/move_to_session_owner",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
                "Idempotency-Key": str(uuid.uuid4()),
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "schedule",
      "id": "sched_lCh70bFOv9IaUYUWyFgTif",
      "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
      "name": "Monday market brief",
      "enabled": true,
      "cron": "0 8 * * 1",
      "timezone": "Europe/London",
      "frequency": "weekly",
      "run_times": ["08:00"],
      "prompt": "Summarise the competitor news of the last 7 days into reports/weekly.md.",
      "target_session": null,
      "create_new_session": true,
      "on_stopped_session": "restart",
      "run_with": "team_key",
      "engine": "claude",
      "last_run_at": "2026-10-12T07:00:00.000Z",
      "last_run_status": "success",
      "next_run_at": "2026-10-19T07:00:00.000Z",
      "created_at": "2026-09-21T13:44:09.000Z",
      "created_by": {
        "id": "user_yFfQdB3rxA41x3cTD5fx2Q",
        "name": "Maya Chen"
      }
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

## Objects [#objects]

<ApiEndpoint>
  <ApiEndpointMain>
    ### Schedule [#schedule]

    <ApiParams title="Attributes">
      <ApiParam name="object" type="string" />

      <ApiParam name="id" type="string" />

      <ApiParam name="team" type="string" />

      <ApiParam name="name" type="string" />

      <ApiParam name="enabled" type="boolean" />

      <ApiParam name="cron" type="string" />

      <ApiParam name="timezone" type="string" />

      <ApiParam name="frequency" type="string" />

      <ApiParam name="run_times" type="array of string" />

      <ApiParam name="prompt" type="string" />

      <ApiParam name="target_session" type="string or null" />

      <ApiParam name="create_new_session" type="boolean" />

      <ApiParam name="on_stopped_session" type="string" />

      <ApiParam name="run_with" type="string or null" />

      <ApiParam name="engine" type="string or null" />

      <ApiParam name="last_run_at" type="string or null" />

      <ApiParam name="last_run_status" type="string or null" />

      <ApiParam name="next_run_at" type="string or null" />

      <ApiParam name="created_at" type="string (date-time)" />

      <ApiParam name="created_by" type="UserRef" />
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The Schedule object"
    {
      "object": "schedule",
      "id": "sched_lCh70bFOv9IaUYUWyFgTif",
      "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
      "name": "Monday market brief",
      "enabled": true,
      "cron": "0 8 * * 1",
      "timezone": "Europe/London",
      "frequency": "weekly",
      "run_times": ["08:00"],
      "prompt": "Summarise the competitor news of the last 7 days into reports/weekly.md.",
      "target_session": null,
      "create_new_session": true,
      "on_stopped_session": "restart",
      "run_with": "team_key",
      "engine": "claude",
      "last_run_at": "2026-10-12T07:00:00.000Z",
      "last_run_status": "success",
      "next_run_at": "2026-10-19T07:00:00.000Z",
      "created_at": "2026-09-21T13:44:09.000Z",
      "created_by": {
        "id": "user_yFfQdB3rxA41x3cTD5fx2Q",
        "name": "Maya Chen"
      }
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ### ScheduleRun [#schedulerun]

    <ApiParams title="Attributes">
      <ApiParam name="object" type="string" />

      <ApiParam name="id" type="string" />

      <ApiParam name="schedule" type="string" />

      <ApiParam name="session" type="string or null" />

      <ApiParam name="status" type="string" />

      <ApiParam name="outcome" type="string or null" />

      <ApiParam name="started_at" type="string (date-time)" />

      <ApiParam name="completed_at" type="string or null" />

      <ApiParam name="tokens_used" type="integer" />

      <ApiParam name="cost_usd" type="number" />

      <ApiParam name="triggered_by" type="UserRef" />
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The ScheduleRun object"
    {
      "object": "schedule_run",
      "id": "run_4K76tZDj56MBIaHaI02P1e",
      "schedule": "sched_lCh70bFOv9IaUYUWyFgTif",
      "session": "sess_U9qrDsTXdBGkZFRLFNOCaR",
      "status": "success",
      "outcome": "proven",
      "started_at": "2026-10-12T07:00:02.000Z",
      "completed_at": "2026-10-12T07:06:48.000Z",
      "tokens_used": 40210,
      "cost_usd": 0.58,
      "triggered_by": {
        "id": "user_yFfQdB3rxA41x3cTD5fx2Q",
        "name": "Maya Chen"
      }
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ### ScheduleRunRequest [#schedulerunrequest]

    <ApiParams title="Attributes">
      <ApiParam name="object" type="string" />

      <ApiParam name="queued" type="boolean" />

      <ApiParam name="run" type="string or null">
        The run id (poll GET /schedules/\{schedule_id}/runs/\{run_id}).
      </ApiParam>

      <ApiParam name="session" type="string or null" />
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The ScheduleRunRequest object"
    {
      "object": "schedule_run_request",
      "queued": true,
      "run": "run_4K76tZDj56MBIaHaI02P1e",
      "session": null
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>
