Scale AI Schedules API

openapi: 3.2.0
info:
  title: Agentex Schedules API
  version: 0.1.0
tags:
- name: Schedules
paths:
  /agents/{agent_id}/schedules:
    post:
      tags:
      - Schedules
      summary: Create Run Schedule
      description: Create a recurring schedule that starts a fresh agent run on each fire.
      operationId: create_run_schedule_agents__agent_id__schedules_post
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRunScheduleRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRunScheduleResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Schedules
      summary: List Run Schedules
      description: List run schedules for an agent.
      operationId: list_run_schedules_agents__agent_id__schedules_get
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          default: 100
          title: Limit
      - name: include_live
        in: query
        required: false
        schema:
          type: boolean
          description: Include live Temporal state and upcoming action times.
          default: false
          title: Include Live
        description: Include live Temporal state and upcoming action times.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRunScheduleListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /agents/{agent_id}/schedules/name/{name}:
    get:
      tags:
      - Schedules
      summary: Get Run Schedule By Name
      description: Get a run schedule by its active name.
      operationId: get_run_schedule_by_name_agents__agent_id__schedules_name__name__get
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      - name: name
        in: path
        required: true
        schema:
          type: string
          title: Name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRunScheduleResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Schedules
      summary: Update Run Schedule By Name
      description: Partially update a run schedule's definition by its active name.
      operationId: update_run_schedule_by_name_agents__agent_id__schedules_name__name__patch
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      - name: name
        in: path
        required: true
        schema:
          type: string
          title: Name
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgentRunScheduleRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRunScheduleResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Schedules
      summary: Delete Run Schedule By Name
      description: Delete a run schedule by its active name.
      operationId: delete_run_schedule_by_name_agents__agent_id__schedules_name__name__delete
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      - name: name
        in: path
        required: true
        schema:
          type: string
          title: Name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /agents/{agent_id}/schedules/{schedule_id}:
    get:
      tags:
      - Schedules
      summary: Get Run Schedule
      description: Get a run schedule by its id.
      operationId: get_run_schedule_agents__agent_id__schedules__schedule_id__get
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      - name: schedule_id
        in: path
        required: true
        schema:
          type: string
          title: Schedule Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRunScheduleResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Schedules
      summary: Update Run Schedule
      description: Partially update a run schedule's definition (cadence, window, input, etc.).
      operationId: update_run_schedule_agents__agent_id__schedules__schedule_id__patch
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      - name: schedule_id
        in: path
        required: true
        schema:
          type: string
          title: Schedule Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgentRunScheduleRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRunScheduleResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Schedules
      summary: Delete Run Schedule
      description: Delete a run schedule permanently.
      operationId: delete_run_schedule_agents__agent_id__schedules__schedule_id__delete
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      - name: schedule_id
        in: path
        required: true
        schema:
          type: string
          title: Schedule Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /agents/{agent_id}/schedules/name/{name}/trigger:
    post:
      tags:
      - Schedules
      summary: Trigger Run Schedule By Name
      description: Trigger an immediate, out-of-band run of the schedule by its active name.
      operationId: trigger_run_schedule_by_name_agents__agent_id__schedules_name__name__trigger_post
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      - name: name
        in: path
        required: true
        schema:
          type: string
          title: Name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRunScheduleResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /agents/{agent_id}/schedules/{schedule_id}/trigger:
    post:
      tags:
      - Schedules
      summary: Trigger Run Schedule
      description: Trigger an immediate, out-of-band run of the schedule (in addition to its cadence).
      operationId: trigger_run_schedule_agents__agent_id__schedules__schedule_id__trigger_post
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      - name: schedule_id
        in: path
        required: true
        schema:
          type: string
          title: Schedule Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRunScheduleResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /agents/{agent_id}/schedules/{schedule_id}/skip:
    post:
      tags:
      - Schedules
      summary: Skip Run Schedule Action
      description: Skip a recurring fire of the schedule.
      operationId: skip_run_schedule_action_agents__agent_id__schedules__schedule_id__skip_post
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      - name: schedule_id
        in: path
        required: true
        schema:
          type: string
          title: Schedule Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkipRunScheduleRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRunScheduleResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /agents/{agent_id}/schedules/{schedule_id}/unskip:
    post:
      tags:
      - Schedules
      summary: Unskip Run Schedule Action
      description: Remove a skip for a recurring fire of the schedule.
      operationId: unskip_run_schedule_action_agents__agent_id__schedules__schedule_id__unskip_post
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      - name: schedule_id
        in: path
        required: true
        schema:
          type: string
          title: Schedule Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnskipRunScheduleRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRunScheduleResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /agents/{agent_id}/schedules/name/{name}/pause:
    post:
      tags:
      - Schedules
      summary: Pause Run Schedule By Name
      description: Pause a run schedule by its active name.
      operationId: pause_run_schedule_by_name_agents__agent_id__schedules_name__name__pause_post
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      - name: name
        in: path
        required: true
        schema:
          type: string
          title: Name
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/PauseRunScheduleRequest'
              - type: 'null'
              title: Request
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRunScheduleResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /agents/{agent_id}/schedules/{schedule_id}/pause:
    post:
      tags:
      - Schedules
      summary: Pause Run Schedule
      description: Pause a run schedule so it stops firing.
      operationId: pause_run_schedule_agents__agent_id__schedules__schedule_id__pause_post
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      - name: schedule_id
        in: path
        required: true
        schema:
          type: string
          title: Schedule Id
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/PauseRunScheduleRequest'
              - type: 'null'
              title: Request
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRunScheduleResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /agents/{agent_id}/schedules/name/{name}/resume:
    post:
      tags:
      - Schedules
      summary: Resume Run Schedule By Name
      description: Resume a paused run schedule by its active name.
      operationId: resume_run_schedule_by_name_agents__agent_id__schedules_name__name__resume_post
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      - name: name
        in: path
        required: true
        schema:
          type: string
          title: Name
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/ResumeRunScheduleRequest'
              - type: 'null'
              title: Request
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRunScheduleResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /agents/{agent_id}/schedules/{schedule_id}/resume:
    post:
      tags:
      - Schedules
      summary: Resume Run Schedule
      description: Resume a paused run schedule so it fires again.
      operationId: resume_run_schedule_agents__agent_id__schedules__schedule_id__resume_post
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      - name: schedule_id
        in: path
        required: true
        schema:
          type: string
          title: Schedule Id
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/ResumeRunScheduleRequest'
              - type: 'null'
              title: Request
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRunScheduleResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    RunScheduleState:
      type: string
      enum:
      - ACTIVE
      - PAUSED
      title: RunScheduleState
      description: Live state of a run schedule, derived from Temporal.
    PauseRunScheduleRequest:
      properties:
        note:
          anyOf:
          - type: string
          - type: 'null'
          title: Note
          description: Optional note explaining the pause.
      type: object
      title: PauseRunScheduleRequest
    ResumeRunScheduleRequest:
      properties:
        note:
          anyOf:
          - type: string
          - type: 'null'
          title: Note
          description: Optional note explaining the resume.
      type: object
      title: ResumeRunScheduleRequest
    ScheduleInitialInput:
      properties:
        type:
          type: string
          const: text
          title: Type
          description: Input content type.
          default: text
        author:
          $ref: '#/components/schemas/MessageAuthor'
          description: The author attributed to the initial input.
          default: user
        content:
          type: string
          title: Content
          description: The initial prompt delivered to the task.
      type: object
      required:
      - content
      title: ScheduleInitialInput
      description: The first input delivered to each freshly created scheduled task.
    AgentRunScheduleResponse:
      properties:
        id:
          type: string
          title: Id
          description: The unique identifier of the run schedule.
        agent_id:
          type: string
          title: Agent Id
          description: The agent this schedule belongs to.
        name:
          type: string
          title: Name
          description: Human-readable schedule name.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Optional description.
        cron_expression:
          anyOf:
          - type: string
          - type: 'null'
          title: Cron Expression
          description: Cron cadence, if cron-based.
        interval_seconds:
          anyOf:
          - type: integer
          - type: 'null'
          title: Interval Seconds
          description: Interval cadence in seconds, if interval-based.
        timezone:
          type: string
          title: Timezone
          description: Timezone the cron expression is evaluated in.
          default: UTC
        start_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Start At
          description: Schedule activation time.
        end_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: End At
          description: Schedule deactivation time.
        paused:
          type: boolean
          title: Paused
          description: Whether the schedule is paused.
          default: false
        task_params:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Task Params
          description: Task params at fire time.
        task_metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Task Metadata
          description: Task metadata at fire time.
        initial_input:
          $ref: '#/components/schemas/ScheduleInitialInput'
          description: The initial input.
        initial_input_method:
          type: string
          title: Initial Input Method
          description: Delivery method, inferred from the agent's ACP type.
        creator_principal:
          anyOf:
          - $ref: '#/components/schemas/ScheduleCreatorPrincipal'
          - type: 'null'
          description: Credential-free creator identity.
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
          description: When the schedule was created.
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
          description: When the schedule was updated.
        state:
          $ref: '#/components/schemas/RunScheduleState'
          description: Live schedule state from Temporal.
          default: ACTIVE
        next_action_times:
          items:
            type: string
            format: date-time
          type: array
          title: Next Action Times
          description: Upcoming scheduled fire times.
        live_data_available:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Live Data Available
          description: Whether requested live Temporal fields were retrieved successfully. Null when live enrichment was not requested.
        skipped_action_times:
          items:
            type: string
            format: date-time
          type: array
          title: Skipped Action Times
          description: Skipped one-off scheduled fire times.
        last_action_time:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Action Time
          description: When the schedule last fired.
        num_actions_taken:
          type: integer
          title: Num Actions Taken
          description: Number of times the schedule has fired.
          default: 0
      type: object
      required:
      - id
      - agent_id
      - name
      - initial_input
      - initial_input_method
      title: AgentRunScheduleResponse
      description: Response model describing a scheduled agent run.
    SkipRunScheduleRequest:
      properties:
        scheduled_time:
          type: string
          format: date-time
          title: Scheduled Time
          description: Specific scheduled fire time to skip.
      type: object
      required:
      - scheduled_time
      title: SkipRunScheduleRequest
    ScheduleCreatorPrincipal:
      properties:
        principal_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Principal Type
          description: e.g. 'user' or 'service_account'.
        user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: User Id
          description: Creator user id, if a user principal.
        service_account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Service Account Id
          description: Creator service-account id, if a service principal.
        account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Id
          description: Account/workspace id of the creator.
      type: object
      title: ScheduleCreatorPrincipal
      description: '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.'
    UpdateAgentRunScheduleRequest:
      properties:
        name:
          anyOf:
          - type: string
            maxLength: 64
            minLength: 1
            pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$
          - type: 'null'
          title: Schedule Name
          description: Human-readable name, unique among active schedules for the agent.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Optional description of what this schedule does.
        cron_expression:
          anyOf:
          - type: string
          - type: 'null'
          title: Cron Expression
          description: New cron cadence. Mutually exclusive with interval_seconds.
        interval_seconds:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Interval Seconds
          description: New interval cadence in seconds. Mutually exclusive with cron_expression.
        timezone:
          anyOf:
          - type: string
          - type: 'null'
          title: Timezone
          description: IANA timezone the cron expression is evaluated in.
        start_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Start At
          description: When the schedule should start being active.
        end_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: End At
          description: When the schedule should stop being active.
        paused:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Paused
          description: Pause/resume the schedule as part of the update.
        task_params:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Task Params
          description: Resolved config forwarded as task `params` at fire time.
        task_metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Task Metadata
          description: Metadata copied onto each created task at fire time.
        initial_input:
          anyOf:
          - $ref: '#/components/schemas/ScheduleInitialInput'
          - type: 'null'
          description: Replacement initial input delivered to each created task.
      type: object
      title: UpdateAgentRunScheduleRequest
      description: 'Partial update for a scheduled agent run.


        Only fields present in the request body are changed. Setting

        ``cron_expression`` clears ``interval_seconds`` and vice versa; providing both

        is rejected.'
    AgentRunScheduleListResponse:
      properties:
        run_schedules:
          items:
            $ref: '#/components/schemas/AgentRunScheduleResponse'
          type: array
          title: Run Schedules
          description: The list of run schedules.
        total:
          type: integer
          title: Total
          description: The number of run schedules returned.
      type: object
      required:
      - run_schedules
      - total
      title: AgentRunScheduleListResponse
      description: Response model for listing run schedules.
    DeleteResponse:
      properties:
        id:
          type: string
          title: Id
        message:
          type: string
          title: Message
      type: object
      required:
      - id
      - message
      title: DeleteResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CreateAgentRunScheduleRequest:
      properties:
        name:
          type: string
          maxLength: 64
          minLength: 1
          pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$
          title: Schedule Name
          description: Human-readable name, unique among active schedules for the agent.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Optional description of what this schedule does.
        cron_expression:
          anyOf:
          - type: string
          - type: 'null'
          title: Cron Expression
          description: Cron expression for the cadence (e.g. '0 17 * * MON-FRI'). Mutually exclusive with interval_seconds.
        interval_seconds:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Interval Seconds
          description: Interval cadence in seconds. Mutually exclusive with cron_expression.
        timezone:
          type: string
          title: Timezone
          description: IANA timezone the cron expression is evaluated in (e.g. 'America/New_York').
          default: UTC
        start_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Start At
          description: When the schedule should start being active.
        end_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: End At
          description: When the schedule should stop being active.
        paused:
          type: boolean
          title: Paused
          description: Whether to create the schedule in a paused state.
          default: false
        task_params:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Task Params
          description: Resolved config forwarded as task `params` at fire time.
        task_metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Task Metadata
          description: Metadata copied onto each created task at fire time.
        initial_input:
          $ref: '#/components/schemas/ScheduleInitialInput'
          description: The first input delivered to each created task.
      type: object
      required:
      - name
      - initial_input
      title: CreateAgentRunScheduleRequest
      description: Request body for creating a scheduled agent run.
    UnskipRunScheduleRequest:
      properties:
        scheduled_time:
          type: string
          format: date-time
          title: Scheduled Time
          description: Specific scheduled fire time to unskip.
      type: object
      required:
      - scheduled_time
      title: UnskipRunScheduleRequest
    MessageAuthor:
      type: string
      enum:
      - user
      - agent
      title: MessageAuthor
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError