> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gp.scale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Run Schedule

> Create a recurring schedule that starts a fresh agent run on each fire.



## OpenAPI

````yaml https://agentex.dev-sgp.scale.com/openapi.json post /agents/{agent_id}/schedules
openapi: 3.1.0
info:
  title: Agentex API
  version: 0.1.0
servers: []
security: []
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'
components:
  schemas:
    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
            - 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.
    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.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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.
    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.
    RunScheduleState:
      type: string
      enum:
        - ACTIVE
        - PAUSED
      title: RunScheduleState
      description: Live state of a run schedule, derived from Temporal.
    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
    MessageAuthor:
      type: string
      enum:
        - user
        - agent
      title: MessageAuthor

````