> ## Documentation Index > Fetch the complete documentation index at: https://cerebrium-kyle-phase0-docs-fixes.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Cerebrium's documentation MCP server is available at https://cerebrium.ai/docs/mcp for searching and querying these docs directly. Install the Cerebrium agent skill with `npx skills add https://cerebrium.ai/docs`. Append .md to any docs page URL to fetch that page as plain Markdown. API keys and authentication tokens are created in the Cerebrium dashboard at https://dashboard.cerebrium.ai. # List Runs > Retrieve a list of runs for a specific app. ## OpenAPI ````yaml https://s3.eu-west-1.amazonaws.com/www.cerebrium.ai/openapi_spec.json get /v2/projects/{project_id}/apps/{app_id}/runs openapi: 3.0.0 info: title: Cerebrium REST API description: >- REST API for interacting with Cerebrium. This API is mainly used by the Cerebrium CLI client, please run `pip install cerebrium` to install it. version: 1.0.0 license: name: Proprietary url: https://www.cerebrium.ai/terms-of-service servers: - url: https://rest.cerebrium.ai security: [] paths: /v2/projects/{project_id}/apps/{app_id}/runs: get: tags: - Runs summary: List Runs description: Retrieve a list of runs for a specific app. operationId: listAppRuns parameters: - name: project_id in: path required: true schema: type: string - name: app_id in: path required: true schema: type: string - name: status in: query required: false description: Filter runs by status. schema: type: string - name: runId in: query required: false description: Retrieve a specific run by its ID. schema: type: string - name: containerId in: query required: false description: Filter runs by the container that executed them. schema: type: string - name: asyncOnly in: query required: false description: Set to true to only return asynchronous runs. schema: type: boolean - name: websocketOnly in: query required: false description: Set to true to only return websocket runs. schema: type: boolean - name: minQueueTimeMs in: query required: false description: Only return runs queued for at least this many milliseconds. schema: type: integer - name: maxQueueTimeMs in: query required: false description: Only return runs queued for at most this many milliseconds. schema: type: integer - name: minContainerQueueTimeMs in: query required: false description: >- Only return runs that waited at least this many milliseconds for a container. schema: type: integer - name: minResponseTimeMs in: query required: false description: >- Only return runs with a response time of at least this many milliseconds. schema: type: integer - name: maxResponseTimeMs in: query required: false description: >- Only return runs with a response time of at most this many milliseconds. schema: type: integer - name: afterDate in: query required: false description: Only return runs created after this timestamp, in RFC3339 format. schema: type: string - name: beforeDate in: query required: false description: Only return runs created before this timestamp, in RFC3339 format. schema: type: string - name: region in: query required: false description: Filter runs by region. schema: type: string - name: nextToken in: query required: false description: Pagination token from a previous response. schema: type: string - name: includeEphemeral in: query required: false description: Include runs from ephemeral apps. Set to true to include them. schema: type: boolean responses: '200': description: A page of runs matching the filters. content: application/json: schema: properties: hitMaxLoops: description: >- Whether the query stopped early before scanning all matching runs. type: boolean items: description: >- Runs ordered by creation time. Each item includes id, modelId, projectId, status, statusCode (integer), async (boolean), websocket (boolean), createdAt, updatedAt, completedAt, containerId, containerStartedAt, functionName, method, region, timing fields in milliseconds (queueTimeMs, runtimeMs, responseTimeMs, activatorQueueTimeMs, containerQueueTimeMs, totalQueueTimeMs, executionTimeMs, totalResponseTimeMs), and for ephemeral runs the run configuration (ephemeral, command, hardware, cpu, memory, gpuCount, createdByUserId). type: array nextToken: description: >- Pagination token to pass as nextToken to retrieve the next page. Empty when there are no more results. type: string type: object '400': description: >- Bad request. The request was malformed or contained invalid parameters. content: application/json: schema: properties: message: description: Human-readable description of the error. type: string type: object '401': description: >- Unauthorized. The Authorization header is missing or the token is invalid. content: application/json: schema: properties: message: description: Human-readable description of the error. type: string type: object security: - BearerAuth: [] components: securitySchemes: BearerAuth: type: http scheme: bearer description: >- Service Account Token authentication. To authenticate API requests: 1. **Create a Service Account Token:** - Go to the [Cerebrium Dashboard](https://dashboard.cerebrium.ai/) and open the **API Keys** page - Click **Create Service Account**, name it (e.g., "GitHub Actions CI/CD"), choose an expiry date, and click **Create** - **Copy the token** generated for the desired service account 2. **Use the Token:** Include the service account token in the Authorization header of API requests: `Authorization: Bearer ` 3. **Best Practices:** - Create separate service accounts for different environments (dev, staging, prod) - Store tokens securely as secrets in consuming applications or workflows - Set appropriate expiry dates and rotate tokens regularly - Never commit tokens to source control For CI/CD integration examples, see the [CI/CD documentation](https://docs.cerebrium.ai/cerebrium/deployments/ci-cd). ````