# Get Task Runs

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

Get task runs

## GET /api/tasks/runs

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/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).",
        "security": [
          {
            "apiKeyAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "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:<account_id>. 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"
                }
              }
            }
          }
        }
      }
    }
  },
  "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"
      }
    }
  }
}
```