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

# Get Tasks

> Retrieve scheduled tasks. Each task includes `recent_runs` (last 5 runs), `upcoming` (next scheduled run times) sourced directly from the Trigger.dev API, and `owner_email` when an account email exists for the task owner. Supports filtering by id, account_id, or artist_account_id.



## OpenAPI

````yaml api-reference/openapi/releases.json GET /api/tasks
openapi: 3.1.0
info:
  title: Recoup API - Releases
  description: >-
    API documentation for the Recoup platform - an AI agent platform for the
    music industry
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.recoupable.dev
security: []
paths:
  /api/tasks:
    get:
      description: >-
        Retrieve scheduled tasks. Each task includes `recent_runs` (last 5
        runs), `upcoming` (next scheduled run times) sourced directly from the
        Trigger.dev API, and `owner_email` when an account email exists for the
        task owner. Supports filtering by id, account_id, or artist_account_id.
      parameters:
        - name: id
          in: query
          description: >-
            Filter by task ID (UUID). Returns a single task matching the
            provided ID. Admin callers may retrieve any task by ID regardless of
            owner; non-admin callers only receive the task if it belongs to
            their authenticated account.
          required: false
          schema:
            type: string
            format: uuid
        - name: account_id
          in: query
          description: Filter tasks to only include those for the specified account.
          required: false
          schema:
            type: string
            format: uuid
        - name: artist_account_id
          in: query
          description: Filter tasks to only include those for the specified artist account.
          required: false
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Tasks retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TasksResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - account_id is outside caller authorization scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error while retrieving tasks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - apiKeyAuth: []
        - bearerAuth: []
components:
  schemas:
    TasksResponse:
      type: object
      required:
        - status
        - tasks
      properties:
        status:
          type: string
          enum:
            - success
            - error
          description: Status of the request
        tasks:
          type: array
          items:
            $ref: '#/components/schemas/Task'
          description: Array of task objects
        error:
          type: string
          description: Error message (only present if status is error)
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
    Task:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the task
        title:
          type: string
          description: Descriptive title or name of the task
        prompt:
          type: string
          description: Detailed instruction or prompt for task execution
        schedule:
          type: string
          description: >-
            Cron expression defining when the task should execute (e.g., '0 10 *
            * *')
        account_id:
          type: string
          format: uuid
          description: Unique identifier for the associated account
        artist_account_id:
          type: string
          format: uuid
          description: Unique identifier for the associated artist account
        enabled:
          type: boolean
          nullable: true
          description: Whether the task is enabled. Defaults to true.
        trigger_schedule_id:
          type: string
          nullable: true
          description: Identifier for the trigger schedule associated with this task
        recent_runs:
          type: array
          items:
            $ref: '#/components/schemas/TaskRunResponse'
          description: Last 5 runs for this task, sourced from the Trigger.dev API.
        upcoming:
          type: array
          items:
            type: string
            format: date-time
          description: >-
            Next scheduled run times, sourced from the latest Trigger.dev run
            payload.
        owner_email:
          type: string
          nullable: true
          description: Primary email address for the task owner account when one exists.
        model:
          type: string
          nullable: true
          minLength: 1
          description: >-
            AI model identifier used when the task runs. When present as a
            string, must be non-empty; otherwise `null` if unset.
    TaskRunResponse:
      type: object
      description: >-
        Raw Trigger.dev SDK run object. The API passes through the SDK response
        without field mapping. See
        https://trigger.dev/docs/management/runs/retrieve for the full
        reference. When listing runs, `output`, `error`, `payload`, and
        `attempts` are not included.
      required:
        - id
        - status
        - taskIdentifier
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          description: The unique run identifier, prefixed with `run_`
        status:
          type: string
          enum:
            - PENDING_VERSION
            - DELAYED
            - QUEUED
            - EXECUTING
            - REATTEMPTING
            - FROZEN
            - COMPLETED
            - CANCELED
            - FAILED
            - CRASHED
            - INTERRUPTED
            - SYSTEM_FAILURE
          description: Current run status
        taskIdentifier:
          type: string
          description: >-
            The task type identifier (e.g. 'setup-sandbox',
            'run-sandbox-command')
        idempotencyKey:
          type: string
          nullable: true
          description: Idempotency key used to deduplicate trigger requests
        version:
          type: string
          description: The worker version that executed the run
        isTest:
          type: boolean
          description: Whether this is a test run
        createdAt:
          type: string
          format: date-time
          description: When the run was created (ISO 8601)
        updatedAt:
          type: string
          format: date-time
          description: When the run was last updated (ISO 8601)
        startedAt:
          type: string
          format: date-time
          nullable: true
          description: When execution started (null if not yet started)
        finishedAt:
          type: string
          format: date-time
          nullable: true
          description: When the run finished (null if still running)
        delayedUntil:
          type: string
          format: date-time
          nullable: true
          description: If delayed, when the run becomes eligible to execute
        ttl:
          description: >-
            Time-to-live. If the run is not started within this duration, it
            expires.
          nullable: true
        expiredAt:
          type: string
          format: date-time
          nullable: true
          description: When the run expired (null if not expired)
        tags:
          type: array
          items:
            type: string
          description: Tags associated with this run (max 10)
        metadata:
          type: object
          nullable: true
          description: JSON metadata attached to the run
        costInCents:
          type: number
          description: Compute cost of the run in cents
        baseCostInCents:
          type: number
          description: Base invocation cost in cents
        durationMs:
          type: number
          description: Compute duration in milliseconds
        env:
          type: object
          description: Environment the run executed in
          properties:
            id:
              type: string
            name:
              type: string
            user:
              type: string
              nullable: true
        depth:
          type: integer
          description: Nesting depth for child runs
        batchId:
          type: string
          nullable: true
          description: Batch ID if triggered as part of a batch
        triggerFunction:
          type: string
          enum:
            - trigger
            - triggerAndWait
            - batchTrigger
            - batchTriggerAndWait
          description: The function used to trigger this run
        payload:
          description: Input payload for the task. Only present when retrieving by runId.
          nullable: true
        output:
          description: >-
            Task output data. Only present when retrieving by runId, and only
            populated when `status` is `COMPLETED`. Shape varies by
            `taskIdentifier`. The `create-content` task returns the schema
            below; other tasks return their own.
          nullable: true
          oneOf:
            - $ref: '#/components/schemas/CreateContentRunOutput'
            - type: object
              description: Generic task output (for tasks not yet schema'd)
        error:
          type: object
          nullable: true
          description: >-
            Error details if the run failed. Only present when retrieving by
            runId.
          properties:
            message:
              type: string
              description: Human-readable error message
            name:
              type: string
              description: Error name or type
            stackTrace:
              type: string
              description: Stack trace
        attempts:
          type: array
          description: Attempt history. Only present when retrieving by runId.
          items:
            type: object
            properties:
              id:
                type: string
                description: Attempt ID, prefixed with `attempt_`
              status:
                type: string
                enum:
                  - PENDING
                  - EXECUTING
                  - PAUSED
                  - COMPLETED
                  - FAILED
                  - CANCELED
              createdAt:
                type: string
                format: date-time
              updatedAt:
                type: string
                format: date-time
              startedAt:
                type: string
                format: date-time
                nullable: true
              completedAt:
                type: string
                format: date-time
                nullable: true
              error:
                type: object
                nullable: true
                properties:
                  message:
                    type: string
                  name:
                    type: string
                  stackTrace:
                    type: string
        schedule:
          type: object
          nullable: true
          description: >-
            Schedule information if triggered by a schedule. Only present when
            retrieving by runId.
        relatedRuns:
          type: object
          nullable: true
          description: >-
            Related run references (root, parent, children). Only present when
            retrieving by runId.
    CreateContentRunOutput:
      type: object
      description: >-
        Output payload for a `create-content` task run. Returned in `output`
        when `status` is `COMPLETED`. Agents should poll
        `/api/tasks/runs?runId=…` and read these fields once the run is done.
      required:
        - videoSourceUrl
        - imageUrl
        - captionText
        - template
      properties:
        videoSourceUrl:
          type: string
          format: uri
          description: >-
            URL to the rendered final 9:16 video (image + motion + audio +
            caption already composed).
        imageUrl:
          type: string
          format: uri
          description: URL to the base image used for video generation.
        captionText:
          type: string
          description: The caption text burned into the video.
        template:
          type: string
          description: >-
            Template id used for this run (e.g. `album-record-store`,
            `artist-caption-bedroom`).
          example: artist-caption-bedroom
        lipsync:
          type: boolean
          description: Whether lipsync was applied (audio-driven mouth animation).
        audio:
          type: object
          description: Metadata about the song clip used in the final composition.
          properties:
            songTitle:
              type: string
            songFilename:
              type: string
            startSeconds:
              type: number
              description: Offset into the source song where the clip starts.
            durationSeconds:
              type: number
              description: Length of the audio clip in seconds.
            clipLyrics:
              type: string
              nullable: true
              description: Lyrics for the chosen clip, when available.
            clipMood:
              type: string
              nullable: true
              description: Inferred mood for the chosen clip, when available.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Your Recoup API key. [Learn more](/quickstart#api-keys).
    bearerAuth:
      type: http
      scheme: bearer

````