> ## 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 Task Runs > Returns task runs for the authenticated account. When `runId` is provided, the response contains that single run (`runs` length 1) or 404 if not found. When `runId` is omitted, returns recent runs filtered by account context (default authenticated account, or `account_id` override when authorized). ## OpenAPI ````yaml api-reference/openapi/releases.json GET /api/tasks/runs 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/runs: get: summary: Get task runs description: >- Returns task runs for the authenticated account. When `runId` is provided, the response contains that single run (`runs` length 1) or 404 if not found. When `runId` is omitted, returns recent runs filtered by account context (default authenticated account, or `account_id` override when authorized). parameters: - name: runId in: query description: >- The unique identifier of a specific task run to retrieve. If omitted, returns a list of recent runs for the authenticated account. required: false schema: type: string - name: limit in: query description: >- Maximum number of runs to return when listing (ignored when runId is provided). Default 20, max 100. required: false schema: type: integer default: 20 minimum: 1 maximum: 100 - name: account_id in: query description: >- Filter runs by account ID. When provided, returns runs tagged with account:. Only applicable when the authenticated account has access to multiple accounts via organization membership. required: false schema: type: string format: uuid responses: '200': description: Task runs retrieved successfully. content: application/json: schema: $ref: '#/components/schemas/TaskRunListResponse' '400': description: >- Bad request - invalid query parameters (for example non-numeric `limit`, out-of-range `limit`, or invalid empty values). content: application/json: schema: $ref: '#/components/schemas/TaskRunsErrorResponse' '401': description: Unauthorized - missing or invalid credentials content: application/json: schema: $ref: '#/components/schemas/TaskRunsErrorResponse' '403': description: >- Forbidden - account_id is not accessible with the provided credentials content: application/json: schema: $ref: '#/components/schemas/TaskRunsErrorResponse' '404': description: Task run not found (only when runId is provided) content: application/json: schema: $ref: '#/components/schemas/TaskRunsErrorResponse' examples: notFound: summary: Unknown run id value: status: error error: Task run not found '500': description: Internal server error while fetching runs from Trigger.dev. content: application/json: schema: $ref: '#/components/schemas/TaskRunsErrorResponse' security: - apiKeyAuth: [] - bearerAuth: [] components: schemas: TaskRunListResponse: type: object required: - status - runs properties: status: type: string enum: - success description: Indicates the request was successful runs: type: array items: $ref: '#/components/schemas/TaskRunResponse' description: >- List of recent task runs for the authenticated account. Each item is a raw Trigger.dev SDK run object (same shape as TaskRunResponse, but without `output` and `error` fields). TaskRunsErrorResponse: type: object required: - status - error properties: status: type: string enum: - error description: Always `error` for this response shape error: type: string description: Human-readable error message 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 ````