Get Task Runs

{
  "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"
          }
        }
      }
    }
  }
}