> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List agent runs

> <Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Authenticate with a platform Bearer credential or full-access workspace key permitted to edit this app. Scoped workspace keys are not accepted. Shares 60 reads or 6 mutations per minute per credential. Responses include request and rate-limit headers; 429 includes Retry-After. List retained manual runs newest first by creation time and identifier. Staff shadow reviews are available only through the staff review API. Default 20, maximum 100. Cursors are scoped to this app and workspace. Includes measured usage when available.



## OpenAPI

````yaml /developers/references/app-management/app-management-openapi.json get /api/apps/{app_id}/imported/agent-runs
openapi: 3.1.0
info:
  title: Base44 App Management API
  version: 1.0.0
servers:
  - url: https://app.base44.com
security:
  - PersonalAccessTokenAuth: []
paths:
  /api/apps/{app_id}/imported/agent-runs:
    get:
      summary: List agent runs
      description: >-
        <Info>This API is in beta. Endpoints, fields, and behavior may still
        change, so avoid depending on it in production.</Info>


        Authenticate with a platform Bearer credential or full-access workspace
        key permitted to edit this app. Scoped workspace keys are not accepted.
        Shares 60 reads or 6 mutations per minute per credential. Responses
        include request and rate-limit headers; 429 includes Retry-After. List
        retained manual runs newest first by creation time and identifier. Staff
        shadow reviews are available only through the staff review API. Default
        20, maximum 100. Cursors are scoped to this app and workspace. Includes
        measured usage when available.
      operationId: list_runs_api_apps__app_id__imported_agent_runs_get
      parameters:
        - name: app_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^[a-f0-9]{24}$
            description: The imported app whose connected repository the agent may read.
            examples:
              - 6820f3a4e7b91d003c45a1f1
            title: App Id
          description: The imported app whose connected repository the agent may read.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            default: 20
            description: >-
              Maximum items, default 20 on the first page. Omit with a cursor to
              reuse its limit.
            examples:
              - 20
            title: Limit
          description: >-
            Maximum items, default 20 on the first page. Omit with a cursor to
            reuse its limit.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
            maxLength: 4096
            description: >-
              Opaque next_cursor from the preceding page of this app's
              collection.
            examples:
              - opaque-cursor
            title: Cursor
          description: Opaque next_cursor from the preceding page of this app's collection.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunList'
              example:
                items:
                  - id: 6820f3a4e7b91d003c45a1f3
                    deployment_id: 6820f3a4e7b91d003c45a1f2
                    status: queued
                    base_sha: bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
                    head_sha: cccccccccccccccccccccccccccccccccccccccc
                    source:
                      kind: github_pull_request
                      number: 12
                    package_digest: >-
                      aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
                    created_date: '2026-10-30T00:00:00Z'
        '400':
          description: 'invalid_cursor: The cursor does not match this query.'
          content:
            application/json:
              examples:
                invalid_cursor:
                  summary: invalid_cursor
                  value:
                    error:
                      code: invalid_cursor
                      message: The cursor does not match this query.
                      details: {}
              schema:
                $ref: '#/components/schemas/StandardErrorEnvelope'
        '401':
          description: 'unauthenticated: Sign in with Bearer credentials.'
          content:
            application/json:
              examples:
                unauthenticated:
                  summary: unauthenticated
                  value:
                    error:
                      code: unauthenticated
                      message: Sign in with Bearer credentials.
                      details: {}
              schema:
                $ref: '#/components/schemas/StandardErrorEnvelope'
        '403':
          description: >-
            forbidden or access_revoked: App, credential or repository access
            denied.
          content:
            application/json:
              examples:
                forbidden:
                  summary: forbidden
                  value:
                    error:
                      code: forbidden
                      message: App or repository access denied.
                      details: {}
              schema:
                $ref: '#/components/schemas/StandardErrorEnvelope'
        '404':
          description: >-
            not_found: The app, deployment or run was not found or the developer
            preview is disabled.
          content:
            application/json:
              examples:
                not_found:
                  summary: not_found
                  value:
                    error:
                      code: not_found
                      message: Agent run not found.
                      details: {}
              schema:
                $ref: '#/components/schemas/StandardErrorEnvelope'
        '409':
          description: >-
            idempotency_conflict, deployment_disabled, repository_changed,
            review_unavailable or publication_unavailable: The request conflicts
            with the current resource.
          content:
            application/json:
              examples:
                idempotency_conflict:
                  summary: idempotency_conflict
                  value:
                    error:
                      code: idempotency_conflict
                      message: Use a new Idempotency-Key for different input.
                      details: {}
              schema:
                $ref: '#/components/schemas/StandardErrorEnvelope'
        '422':
          description: >-
            invalid_request or review_too_large: Invalid request, or the
            rendered review exceeds the 60,000-byte publication limit.
          content:
            application/json:
              examples:
                invalid_request:
                  summary: invalid_request
                  value:
                    error:
                      code: invalid_request
                      message: The agent manifest is invalid.
                      details: {}
              schema:
                $ref: '#/components/schemas/StandardErrorEnvelope'
        '429':
          description: 'rate_limited: Retry after Retry-After seconds.'
          content:
            application/json:
              examples:
                rate_limited:
                  summary: rate_limited
                  value:
                    error:
                      code: rate_limited
                      message: Too many agent requests.
                      details: {}
              schema:
                $ref: '#/components/schemas/StandardErrorEnvelope'
        '503':
          description: >-
            Database temporarily unavailable (`database_unavailable`): the data
            cluster did not answer in time. Retry after the `Retry-After`
            seconds.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorEnvelope'
              examples:
                database_unavailable:
                  summary: database_unavailable
                  value:
                    error:
                      code: database_unavailable
                      message: Database temporarily unavailable, please retry
                      details: {}
      security:
        - PersonalAccessTokenAuth:
            - read_only
        - WorkspaceApiKeyAuth:
            - read_only
        - WorkspaceApiKeyBearerAuth:
            - read_only
components:
  schemas:
    RunList:
      properties:
        items:
          items:
            $ref: '#/components/schemas/RunResponse'
          type: array
          title: Items
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
      type: object
      required:
        - items
        - next_cursor
      title: RunList
    StandardErrorEnvelope:
      properties:
        error:
          $ref: '#/components/schemas/StandardError'
          description: What went wrong.
      type: object
      required:
        - error
      title: StandardErrorEnvelope
      description: The error body returned in the standard envelope.
    RunResponse:
      properties:
        id:
          type: string
          title: Id
        deployment_id:
          type: string
          title: Deployment Id
        status:
          type: string
          enum:
            - queued
            - running
            - cancelling
            - cancelled
            - succeeded
            - failed
            - timed_out
          title: Status
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Code
        base_sha:
          type: string
          title: Base Sha
        head_sha:
          type: string
          title: Head Sha
        source:
          anyOf:
            - $ref: '#/components/schemas/ChangeSource'
            - type: 'null'
        package_digest:
          type: string
          title: Package Digest
        created_date:
          type: string
          title: Created Date
        started_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Started At
        finished_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Finished At
        result:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Result
          description: >-
            Validated output, source identity and coverage. Available for 30
            days. Never the full source snapshot.
        usage:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Usage
          description: >-
            Observed tokens, duration and provider cost where available. Null
            means unmeasured, not zero.
      type: object
      required:
        - id
        - deployment_id
        - status
        - error_code
        - base_sha
        - head_sha
        - source
        - package_digest
        - created_date
        - started_at
        - finished_at
        - result
        - usage
      title: RunResponse
    StandardError:
      properties:
        code:
          type: string
          title: Code
          description: >-
            Stable machine-readable cause of the failure. Match on this, not on
            `message`.
          example: not_found
        message:
          type: string
          title: Message
          description: Human-readable explanation. It isn't a stable contract.
          example: App not found
        details:
          additionalProperties: true
          type: object
          title: Details
          description: >-
            Structured context for the failure, or an empty object when there's
            none.
          example: {}
      type: object
      required:
        - code
        - message
      title: StandardError
    ChangeSource:
      properties:
        kind:
          type: string
          const: github_pull_request
          title: Kind
        number:
          type: integer
          minimum: 1
          title: Number
      additionalProperties: false
      type: object
      required:
        - kind
        - number
      title: ChangeSource
  securitySchemes:
    PersonalAccessTokenAuth:
      type: http
      scheme: bearer
      description: >-
        Personal access token, sent as `Authorization: Bearer <token>`. Each
        operation lists the permission it needs: `read_only` or `full_access`. A
        full-access token can call every operation. A read-only token can call
        only the operations that list `read_only`; anything else returns 403
        `read_only_credential_route_not_allowed`.
    WorkspaceApiKeyAuth:
      type: apiKey
      in: header
      name: api_key
      description: >-
        Workspace API key, sent as `api_key: <key>`. Each operation that accepts
        one lists what the key needs: a permission, `read_only` or
        `full_access`, like a personal access token, or a scope. A key without
        the scope gets 403 `workspace_api_key_scope_required`.
    WorkspaceApiKeyBearerAuth:
      type: http
      scheme: bearer
      description: >-
        Workspace API key, sent as `Authorization: Bearer <key>`. Accepted
        wherever `api_key` is, with the same permission.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.