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

# Run New Task

> Create a new task and task run.

If wait_for_completion is false (default), the task executes in the background via Cloud Tasks
and returns immediately with the task ID and run ID.
If wait_for_completion is true, waits for task completion and returns the result.



## OpenAPI

````yaml cloud-api-reference/openapi.json post /runs
openapi: 3.1.0
info:
  title: Webagent API
  description: API to execute automated tasks on browser using different LLM providers.
  version: 0.1.0
servers:
  - url: https://api.webagent.cloud
    description: Webagent API
security: []
paths:
  /runs:
    post:
      tags:
        - run
      summary: Run New Task
      description: >-
        Create a new task and task run.


        If wait_for_completion is false (default), the task executes in the
        background via Cloud Tasks

        and returns immediately with the task ID and run ID.

        If wait_for_completion is true, waits for task completion and returns
        the result.
      operationId: run_new_task_runs_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Run'
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    AgentRequest:
      properties:
        json_schema:
          anyOf:
            - type: string
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Json Schema
          description: The JSON schema for the task result
        prompt:
          type: string
          minLength: 3
          title: Prompt
          description: The task to be performed by the agent
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
          description: The model to use for the task. Defaults to 'gpt-4.1'.
          default: gpt-4.1
        provider:
          anyOf:
            - type: string
            - type: 'null'
          title: Provider
          description: The provider to use for the task. Defaults to 'openai'.
          default: openai
        webhook_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Webhook Url
          description: The webhook URL to send the result to
        response_format:
          anyOf:
            - type: string
            - type: 'null'
          title: Response Format
          description: Whether to return the result as text or JSON
          default: text
        auth_context_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Auth Context Id
          description: The id of associated auth context
        initial_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Initial Url
          description: The initial URL to navigate to before executing the task
        session_timeout:
          anyOf:
            - type: integer
            - type: 'null'
          title: Session Timeout
          description: The timeout for the task in seconds
          default: 900
        wait_for_completion:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Wait For Completion
          description: >-
            Whether to wait for the task to complete before returning the
            response. If false, the task will be executed in the background and
            the response will contain only the task ID.
          default: false
      type: object
      required:
        - prompt
      title: AgentRequest
      description: Request model for creating a new task and task run.
    Run:
      properties:
        id:
          type: string
          title: Id
          description: The ID of the created task run
        task_id:
          type: string
          title: Task Id
          description: The ID of the created task
        status:
          $ref: '#/components/schemas/StatusEnum'
          description: The status of the agent's task
          default: pending
        result:
          anyOf:
            - {}
            - type: 'null'
          title: Result
          description: The final result of the agent's task
        is_done:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Done
          description: Whether the agent has completed its task
        is_successful:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Successful
          description: Whether the agent was successful in completing its task
      type: object
      required:
        - id
        - task_id
      title: Run
      description: Represents a Run.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    StatusEnum:
      type: string
      enum:
        - success
        - failure
        - pending
      title: StatusEnum
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key

````