# Get Tasks

Source: https://recoupable.dev/docs/api-reference/tasks/get

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.

## GET /api/tasks

Full OpenAPI specification: https://recoupable.dev/docs/spec/releases.json

## Authentication

This operation requires one of the security alternatives in the specification below. Security scheme definitions are included where present in the published specification.

[Authentication guide](https://recoupable.dev/docs/authentication)

## Operation and referenced schemas

```json
{
  "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"
    }
  ],
  "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.",
        "security": [
          {
            "apiKeyAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "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"
                }
              }
            }
          }
        }
      }
    }
  },
  "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 * * *')"
          },
          "timezone": {
            "type": "string",
            "nullable": true,
            "description": "IANA time zone the task's cron is interpreted in, read from the Trigger.dev schedule (the source of truth). Null when the task has no schedule or the timezone can't be read.",
            "example": "America/New_York"
          },
          "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."
          },
          "owner_email": {
            "type": "string",
            "nullable": true,
            "description": "Primary email address for the task owner account when one exists."
          },
          "artist_name": {
            "type": "string",
            "nullable": true,
            "description": "Display name of the artist account the task runs for (`artist_account_id`), so a task list can label rows without a roster lookup. Null when the artist account no longer exists.",
            "example": "Braden Bales"
          },
          "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"
      }
    }
  }
}
```