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

# List tasks

> Returns a paginated list of tasks in the authenticated workspace. Soft-deleted tasks are never returned.



## OpenAPI

````yaml GET /task
openapi: 3.0.1
info:
  title: Tela API
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.tela.com
security: []
paths:
  /task:
    get:
      tags:
        - Task
      summary: List tasks
      description: >
        Returns a paginated list of tasks in the authenticated workspace.
        Soft-deleted tasks are never returned.


        Filtering notes (derived from the server implementation):

        - `promptApplicationId` and `agentId` cannot be combined (400).
        `promptApplicationId` restricts to tasks with `sourceType: prompt`;
        `agentId` restricts to `sourceType: agent`.

        - The three date ranges (`approvedAt*`, `createdAt*`, `updatedAt*`) are
        each applied as a range, but when more than one range is supplied they
        are combined with **OR**, not AND.

        - `createdBy` and `approvedBy` are likewise combined with **OR** when
        both are supplied.

        - Results are ordered by `orderBy` (default `updatedAt`) with `id`
        always appended as a stable tie-breaker.


        Error bodies have the shape `{ code, message, status, name: "Error",
        details? }`.
      parameters:
        - name: limit
          in: query
          required: false
          description: Page size. Defaults to 10 and is clamped to the range 1–100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: offset
          in: query
          required: false
          description: Number of tasks to skip. Defaults to 0.
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: objectLinks
          in: query
          required: false
          description: >-
            When `true`, `meta.links.*` are returned as objects (`{ ...filters,
            limit, offset }`) instead of query strings.
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
        - name: status
          in: query
          required: false
          description: >-
            JSON-encoded array of statuses, e.g. `["completed","failed"]`. The
            raw value is passed through `JSON.parse`, so it must be valid JSON.
          schema:
            type: string
          example: '["completed","validating"]'
        - name: since
          in: query
          required: false
          deprecated: true
          description: >-
            [DEPRECATED] Alias for `approvedAtSince`. Ignored when
            `approvedAtSince` is also provided.
          schema:
            type: string
        - name: until
          in: query
          required: false
          deprecated: true
          description: >-
            [DEPRECATED] Alias for `approvedAtUntil`. Ignored when
            `approvedAtUntil` is also provided.
          schema:
            type: string
        - name: approvedAtSince
          in: query
          required: false
          description: >-
            Lower bound (inclusive) on `approvedAt`. Any value accepted by
            JavaScript `new Date()` (ISO 8601 recommended).
          schema:
            type: string
            format: date-time
        - name: approvedAtUntil
          in: query
          required: false
          description: Upper bound (inclusive) on `approvedAt`.
          schema:
            type: string
            format: date-time
        - name: createdAtSince
          in: query
          required: false
          description: Lower bound (inclusive) on `createdAt`.
          schema:
            type: string
            format: date-time
        - name: createdAtUntil
          in: query
          required: false
          description: Upper bound (inclusive) on `createdAt`.
          schema:
            type: string
            format: date-time
        - name: updatedAtSince
          in: query
          required: false
          description: Lower bound (inclusive) on `updatedAt`.
          schema:
            type: string
            format: date-time
        - name: updatedAtUntil
          in: query
          required: false
          description: Upper bound (inclusive) on `updatedAt`.
          schema:
            type: string
            format: date-time
        - name: approvedBy
          in: query
          required: false
          description: >-
            Approver emails to match. Declared as an array in the route schema;
            repeat the parameter to pass several values
            (`approvedBy=a@x.com&approvedBy=b@x.com`). Whether a comma-separated
            single value is also accepted depends on the framework query parser
            and was not verified.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: createdBy
          in: query
          required: false
          description: Creator emails to match. Same encoding rules as `approvedBy`.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: promptApplicationId
          in: query
          required: false
          description: >-
            Restrict to tasks of this Workstation/App (`sourceType: prompt`).
            The app must be accessible to the caller (404 otherwise). Cannot be
            combined with `agentId`.
          schema:
            type: string
            format: uuid
        - name: agentId
          in: query
          required: false
          description: >-
            Restrict to tasks of this agent (`sourceType: agent`). Cannot be
            combined with `promptApplicationId`.
          schema:
            type: string
            format: uuid
        - name: promptVersionId
          in: query
          required: false
          description: >-
            Restrict to tasks executed with this Canvas version. The version
            must be accessible to the caller (404 otherwise).
          schema:
            type: string
            format: uuid
        - name: completionRunId
          in: query
          required: false
          description: Restrict to tasks linked to this completion run.
          schema:
            type: string
            format: uuid
        - name: orderBy
          in: query
          required: false
          description: >-
            Sort field. Either a single field name or a JSON-encoded array of
            field names for multi-column sorting, e.g. `["status","createdAt"]`.
            Defaults to `updatedAt`. Allowed values: `name`, `reference`,
            `approvedAt`, `createdAt`, `updatedAt`, `id`, `status`,
            `approvedBy`, `createdBy`. `status` sorts by lifecycle order rather
            than alphabetically.
          schema:
            type: string
          example: createdAt
        - name: order
          in: query
          required: false
          description: Sort direction. Defaults to `desc`.
          schema:
            type: string
            default: desc
            enum:
              - asc
              - desc
        - name: ids
          in: query
          required: false
          description: >-
            JSON-encoded array of task IDs to return, e.g.
            `["<uuid>","<uuid>"]`.
          schema:
            type: string
        - name: taskName
          in: query
          required: false
          description: Case-insensitive substring match on the task name.
          schema:
            type: string
        - name: excludeInputOutputColumns
          in: query
          required: false
          description: >-
            When `true`, omits `rawInput`, `inputContent` and
            `originalOutputContent` from each task and adds a lightweight
            `inputFiles` summary instead (unless `excludeInputFiles` is also
            `true`).
          schema:
            type: boolean
            default: false
        - name: excludeInputFiles
          in: query
          required: false
          description: >-
            Only meaningful together with `excludeInputOutputColumns=true`;
            suppresses the `inputFiles` summary.
          schema:
            type: boolean
            default: false
        - name: excludeOutputContent
          in: query
          required: false
          description: When `true`, omits `outputContent` from each task.
          schema:
            type: boolean
            default: false
        - name: tags
          in: query
          required: false
          description: >-
            Tags the task must contain (all of them). Accepts either a
            JSON-encoded array (`["a","b"]`) or a comma-separated list (`a,b`).
            Values are trimmed and de-duplicated.
          schema:
            type: string
          example: priority,reviewed
      responses:
        '200':
          description: Paginated list of tasks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskListResponse'
        '400':
          description: >-
            Invalid query (for example `promptApplicationId` and `agentId` used
            together, or a non-JSON `status`/`ids`/`orderBy` array)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: >-
            The referenced app or Canvas version was not found or is not
            accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    TaskListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Task'
        meta:
          $ref: '#/components/schemas/TaskPaginationMeta'
      required:
        - data
        - meta
      example:
        data:
          - id: 8b6d2c9a-1f4e-4c1b-9a1e-3c2d5e6f7a80
            reference: 42
            name: Invoice-2025-001.pdf
            status: completed
            rawInput:
              application_id: 95cec438-6080-44fe-8275-28b16bd40178
              variables:
                document:
                  files:
                    - file_url: https://example.com/invoice.pdf
                      file_name: Invoice-2025-001.pdf
                      mime_type: application/pdf
            inputContent:
              variables:
                document:
                  files:
                    - file_url: https://example.com/invoice.pdf
                      file_name: Invoice-2025-001.pdf
                      mime_type: application/pdf
              messages: []
              files:
                - name: document
                  filename: Invoice-2025-001.pdf
                  url: https://example.com/invoice.pdf
                  usedAt: variables
                  mimeType: application/pdf
            outputContent:
              role: assistant
              content:
                cliente: Acme Corporation
                valor: 150000
            originalOutputContent:
              role: assistant
              content:
                cliente: Acme Corporation
                valor: 150000
            createdBy: api@company.com
            approvedBy: reviewer@company.com
            approvedAt: '2025-01-15T11:00:00.000Z'
            completionRunId: b83b1558-de5b-4e45-b517-7bececbdd154
            workflowRunId: null
            sourceType: prompt
            agentId: null
            agentRef: null
            agentSessionId: null
            promptVersionId: 76065caa-c519-441a-8fe2-cc43e29664ab
            promptApplicationId: 95cec438-6080-44fe-8275-28b16bd40178
            workspaceId: 3f55cfd9-4427-4887-a181-d9ad39967802
            metadata: null
            tags:
              - priority
            createdAt: '2025-01-15T10:30:00.000Z'
            updatedAt: '2025-01-15T11:00:00.000Z'
            deletedAt: null
        meta:
          totalCount: 142
          limit: 10
          offset: 0
          currentPage: 1
          totalPages: 15
          lastReference: 142
          links:
            first: >-
              ?promptApplicationId=95cec438-6080-44fe-8275-28b16bd40178&limit=10&offset=0
            last: >-
              ?promptApplicationId=95cec438-6080-44fe-8275-28b16bd40178&limit=10&offset=140
            next: >-
              ?promptApplicationId=95cec438-6080-44fe-8275-28b16bd40178&limit=10&offset=10
            previous: null
    Error: {}
    Task:
      type: object
      title: Task
      properties:
        id:
          type: string
          format: uuid
        reference:
          type: integer
          nullable: true
          description: >-
            Sequential number of the task within its app/agent. Assigned shortly
            after creation.
        name:
          type: string
        status:
          $ref: '#/components/schemas/TaskStatus'
        rawInput:
          $ref: '#/components/schemas/TaskRawInput'
        inputContent:
          $ref: '#/components/schemas/TaskInputContent'
        outputContent:
          type: object
          nullable: true
          additionalProperties: true
          description: >-
            Current output. For Canvas tasks this is the assistant message
            (`role`, `content`, …) where `content` holds the extracted fields;
            for workflow tasks it wraps `{ response, stepOutputs, error? }`.
            Reflects reviewer edits.
        originalOutputContent:
          type: object
          nullable: true
          additionalProperties: true
          description: >-
            Output as originally produced by the execution, before any reviewer
            edits.
        createdBy:
          type: string
          description: Email of the identity that created the task.
        approvedBy:
          type: string
          nullable: true
        approvedAt:
          type: string
          format: date-time
          nullable: true
        completionRunId:
          type: string
          format: uuid
          nullable: true
        workflowRunId:
          type: string
          format: uuid
          nullable: true
        sourceType:
          $ref: '#/components/schemas/TaskSourceType'
        agentId:
          type: string
          format: uuid
          nullable: true
        agentRef:
          type: string
          nullable: true
          description: Published agent identifier (agent tasks only).
        agentSessionId:
          type: string
          nullable: true
        promptVersionId:
          type: string
          format: uuid
          nullable: true
          description: >-
            Canvas version the task was executed with (Workstation/App tasks
            only).
        promptApplicationId:
          type: string
          format: uuid
          nullable: true
        workspaceId:
          type: string
          format: uuid
        metadata:
          $ref: '#/components/schemas/TaskMetadata'
        tags:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        deletedAt:
          type: string
          format: date-time
          nullable: true
        inputFiles:
          type: array
          description: >-
            Only present on `GET /task` when `excludeInputOutputColumns=true`
            (and `excludeInputFiles` is not set). Summary of
            `inputContent.files` without parser payloads.
          items:
            type: object
            properties:
              name:
                type: string
              filename:
                type: string
              type:
                type: string
              url:
                type: string
              mimeType:
                type: string
              jobId:
                type: string
              pages:
                type: number
              usedAt:
                type: string
                enum:
                  - variables
                  - messages
      required:
        - id
        - name
        - status
        - createdBy
        - sourceType
        - workspaceId
        - tags
        - createdAt
        - updatedAt
    TaskPaginationMeta:
      type: object
      title: Pagination metadata
      properties:
        totalCount:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
        currentPage:
          type: integer
        totalPages:
          type: integer
        lastReference:
          type: integer
          description: >-
            Highest `reference` among the app's/agent's non-deleted tasks (`0`
            when neither `promptApplicationId` nor `agentId` was given). Only
            present on `GET /task`.
        links:
          type: object
          description: >-
            Links to other pages. Query strings (e.g.
            `?promptApplicationId=…&limit=10&offset=10`) by default, or objects
            (`{ ...filters, limit, offset }`) when `objectLinks=true`.
          properties:
            first:
              oneOf:
                - type: string
                - type: object
                  additionalProperties: true
            last:
              oneOf:
                - type: string
                - type: object
                  additionalProperties: true
            next:
              nullable: true
              oneOf:
                - type: string
                - type: object
                  additionalProperties: true
            previous:
              nullable: true
              oneOf:
                - type: string
                - type: object
                  additionalProperties: true
          required:
            - first
            - last
            - next
            - previous
      required:
        - totalCount
        - limit
        - offset
        - currentPage
        - totalPages
        - links
    TaskStatus:
      type: string
      description: >-
        Task lifecycle status. `created` (agent tasks awaiting execution) →
        `running` → `validating` (output ready, awaiting review) → `completed`
        (approved). `failed` and `cancelled` are terminal.
      enum:
        - created
        - running
        - validating
        - completed
        - failed
        - cancelled
    TaskRawInput:
      type: object
      nullable: true
      title: Raw input
      description: >-
        The completion request the task is executed with. Same shape as the
        `/v2/chat/completions` body; `application_id` is set by the server from
        `promptApplicationId`.
      properties:
        application_id:
          type: string
          format: uuid
          description: >-
            Set by the server; any value you send is overwritten with
            `promptApplicationId`.
        canvas_id:
          type: string
          format: uuid
        version_id:
          type: string
          format: uuid
        environment_name:
          type: string
        variables:
          type: object
          description: >-
            Variables keyed by the app's variable names. Files are passed here
            (see `TaskVariableValue`).
          additionalProperties:
            $ref: '#/components/schemas/TaskVariableValue'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/TaskMessage'
        input:
          type: string
        webhook_url:
          type: string
          description: URL that receives a POST when the execution finishes.
        override:
          $ref: '#/components/schemas/Override'
        stream:
          type: boolean
        async:
          type: boolean
        long_response:
          type: boolean
        label:
          type: string
        tags:
          type: array
          items:
            type: string
    TaskInputContent:
      type: object
      nullable: true
      title: Input content
      description: >-
        Normalized input of the execution. `null` until the run has been
        prepared.
      properties:
        variables:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/TaskInternalVariableContent'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/TaskMessage'
        files:
          type: array
          items:
            $ref: '#/components/schemas/TaskInputFile'
    TaskSourceType:
      type: string
      description: >-
        Whether the task belongs to a Workstation/App (`prompt`) or to an agent
        (`agent`).
      enum:
        - prompt
        - agent
    TaskMetadata:
      type: object
      nullable: true
      title: Task metadata
      properties:
        resourceContext:
          $ref: '#/components/schemas/TaskResourceContext'
        editedFields:
          type: array
          description: >-
            Paths inside `outputContent.content` edited by reviewers via `PATCH
            /task/{id}`.
          items:
            type: object
            properties:
              path:
                type: string
              author:
                type: string
              editedAt:
                type: string
                format: date-time
              previousValue: {}
            required:
              - path
              - author
              - editedAt
        approvalRevokedBy:
          type: string
        approvalRevokedAt:
          type: string
          format: date-time
        sourceFile:
          type: object
          description: Provenance of tasks created from a spreadsheet/CSV import.
          properties:
            filename:
              type: string
            mimeType:
              type: string
            fileSize:
              type: number
            totalRows:
              type: number
            rowIndex:
              type: number
            uploadedAt:
              type: string
              format: date-time
            uploadedBy:
              type: string
          required:
            - filename
    TaskVariableValue:
      description: >-
        Value of a variable when creating a task. A string for text variables; a
        file object for a single file; `{ files: [...] }` for several files; `{
        text, files }` for mixed content.
      oneOf:
        - type: string
          title: Text
        - $ref: '#/components/schemas/TaskVariableFile'
        - type: object
          title: Files
          properties:
            files:
              type: array
              items:
                $ref: '#/components/schemas/TaskVariableFile'
          required:
            - files
        - type: object
          title: Mixed
          properties:
            text:
              oneOf:
                - type: string
                - type: object
                  additionalProperties:
                    type: string
            files:
              type: array
              items:
                $ref: '#/components/schemas/TaskVariableFile'
          required:
            - text
            - files
    TaskMessage:
      type: object
      properties:
        role:
          type: string
        content:
          description: A string, a single content part, or an array of content parts.
          oneOf:
            - type: string
            - $ref: '#/components/schemas/TaskMessageContentPart'
            - type: array
              items:
                $ref: '#/components/schemas/TaskMessageContentPart'
        function_call:
          type: object
          properties:
            name:
              type: string
            arguments:
              type: string
          required:
            - name
            - arguments
      required:
        - role
        - content
    Override:
      type: object
      description: >-
        Override default settings specified in the canvas. This allows for
        fine-tuning the completion behavior for this specific request.
      properties:
        model:
          type: string
          description: >-
            The specific model to use for this completion. If not specified, the
            default model set in the canvas will be used.
        temperature:
          type: number
          description: >-
            Controls randomness in the output. Values between 0 and 1. Lower
            values make the output more focused and deterministic.
        type:
          type: string
          enum:
            - chat
            - completion
          description: Specifies whether to use a chat or completion model.
        functions:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              description:
                type: string
              parameters:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - object
                  properties:
                    type: object
                    additionalProperties: true
                  required:
                    type: array
                    items:
                      type: string
          description: >-
            An array of functions that the model can call. This allows for more
            structured and interactive completions.
        structured_output:
          type: object
          properties:
            enabled:
              type: boolean
              description: Whether to enable structured output for this completion.
            schema:
              type: object
              properties:
                properties:
                  type: object
                  additionalProperties: true
                  description: Defines the properties of the structured output
                type:
                  type: string
                  enum:
                    - object
                  description: >-
                    The type of the schema, always "object" for structured
                    output
                title:
                  type: string
                  description: The title of the schema
                description:
                  type: string
                  description: A description of the schema
                required:
                  type: array
                  items:
                    type: string
                  description: An array of required property names
              description: >-
                The schema defining the structure of the output. This is used
                when structured output is enabled.
          description: Configuration for generating structured output.
      required:
        - type
    TaskInternalVariableContent:
      description: >-
        Normalized variable value as stored on the task. A string, `{ files:
        [...] }`, or `{ text, files }` (a single file object is normalized into
        `files`).
      oneOf:
        - type: string
        - type: object
          properties:
            files:
              type: array
              items:
                $ref: '#/components/schemas/TaskVariableFile'
          required:
            - files
        - type: object
          properties:
            text:
              oneOf:
                - type: string
                - type: object
                  additionalProperties:
                    type: string
            files:
              type: array
              items:
                $ref: '#/components/schemas/TaskVariableFile'
          required:
            - text
            - files
    TaskInputFile:
      type: object
      description: >-
        A file that took part in the execution, either from a variable (`usedAt:
        variables`) or from a message (`usedAt: messages`).
      properties:
        name:
          type: string
          description: Variable name, or `message-{index}` for files found in messages.
        type:
          type: string
        usedAt:
          type: string
          enum:
            - variables
            - messages
        url:
          type: string
        mimeType:
          type: string
        jobId:
          type: string
          description: Parser job identifier, when the file was parsed.
        filename:
          type: string
        pages:
          type: number
        parserData:
          type: object
          additionalProperties: true
          description: Parser result payload (structure not documented here).
        filePagesAsImage:
          type: array
          items:
            type: string
    TaskResourceContext:
      type: object
      description: >-
        Set by the server on tasks that run against a resource shared from
        another workspace (federated). Client-supplied values are discarded.
      properties:
        isFederated:
          type: boolean
        entitlementId:
          type: string
          nullable: true
        executionWorkspaceId:
          type: string
        billingWorkspaceId:
          type: string
        resourceWorkspaceId:
          type: string
        credentialWorkspaceId:
          type: string
        projectId:
          type: string
          nullable: true
    TaskVariableFile:
      type: object
      title: File
      properties:
        file_url:
          type: string
          description: Publicly reachable URL or a `vault://` reference of the file.
        file_name:
          type: string
        mime_type:
          type: string
        vault_reference:
          type: string
        options:
          type: object
          properties:
            range:
              type: array
              description: Page range to process (e.g. for PDFs).
              items:
                type: number
      required:
        - file_url
    TaskMessageContentPart:
      oneOf:
        - type: object
          title: Text part
          properties:
            type:
              type: string
              enum:
                - text
            text:
              type: string
          required:
            - type
            - text
        - type: object
          title: Image part
          properties:
            type:
              type: string
              enum:
                - image_url
            image_url:
              type: object
              properties:
                url:
                  type: string
                detail:
                  type: string
                  enum:
                    - auto
                    - high
                    - low
              required:
                - url
          required:
            - type
            - image_url
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT or UUID

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.