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

# Run Asynchronously

> Run a runnable asynchronously

Run a runnable asynchronously. The request will return immediately with a run ID that can be used to check the status and retrieve results.

The request may optionally specify a `callback_url` and `callback_headers` to be used for the run results. When the run completes, re-factor will perform a `POST` request to the callback URL with the results or an error message.


## OpenAPI

````yaml POST /v1/runnable/{id}/runs?mode=async
openapi: 3.1.0
info:
  title: re-factor API Reference
  version: 1.0.0
  description: API specification for re-factor system based on schema definitions
servers: []
security:
  - BearerAuth: []
paths:
  /v1/runnable/{id}/runs?mode=async:
    post:
      summary: Run a runnable asynchronously
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                resources:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        description: Name of the resource
                      resource:
                        oneOf:
                          - type: object
                            required:
                              - id
                            properties:
                              id:
                                type: string
                                format: uuid
                                description: >-
                                  The pre-existing ID of the resource, if you've
                                  already created it.
                          - $ref: '#/components/schemas/ResourceCreate'
                        description: >-
                          Resource to use under the `name` key for the run. Can
                          be a string ID or a full resource object.
                  description: Resources to embed within the runtime
                timeout_seconds:
                  type: integer
                  description: >-
                    Timeout in seconds. If null or less than 1, no timeout is
                    set.
                  default: 0
                telemetry_strategy:
                  type: string
                  enum:
                    - disable
                    - default
                    - force
                  default: default
                  description: >-
                    Telemetry strategy to use for the run. `disable` will
                    disable telemetry, `force` will force telemetry, and
                    `default` will use the runnable's default telemetry
                    strategy.
                callback_url:
                  type: string
                  format: uri
                  description: >-
                    Callback URL to use for the run. If null, no callback will
                    be executed and run results can be retrieved using the `GET
                    /v1/run/{run_id}` endpoint. If provided, when the runnable
                    has completed, it will make a POST request to the callback
                    URL with the run results or an error message.
                callback_headers:
                  type: object
                  additionalProperties:
                    type: string
                  description: >-
                    Headers to use for the callback request. Only used if
                    `callback_url` is provided.
      responses:
        '202':
          description: Asynchronous invocation reference
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunReference'
components:
  schemas:
    ResourceCreate:
      type: object
      required:
        - name
        - directory_path
      properties:
        content:
          type: string
          description: >-
            The file to upload. This can be provided instead of `uri`. It should
            be a base64-encoded string of the format
            `data:<MIME_TYPE>;base64,<BASE64_ENCODED_CONTENT>`.
        uri:
          type: string
          format: uri
          description: >-
            The URI of the file to upload. This can be provided instead of
            `content`.
        name:
          type: string
          description: Name of the resource
        tags:
          type: array
          items:
            type: string
          description: Tags for the resource
        directory_path:
          type: string
          description: Path to the directory where the resource should be stored
        metadata:
          type: object
          additionalProperties: true
          description: Additional metadata for the resource
    RunReference:
      type: object
      properties:
        id:
          type: string
          description: >-
            The id of the run. This can be used to query the status of the run
            or fetch its output.
      required:
        - id
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````