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

# Retrieve a background task

> Retrieve a background task's status, progress and results.

Endpoints that cannot answer within one request queue a task and hand back its id -- for example
`POST /frameworks/{frameworkId}/export`. Poll this endpoint until `complete` is `true`, then read
what the task produced from `outputs`.




## OpenAPI

````yaml get /background-tasks/{taskId}
openapi: 3.0.3
info:
  contact:
    email: support@openlayer.com
    name: Openlayer
    url: https://openlayer.com/
  description: API for interacting with the Openlayer server.
  title: Openlayer API
  version: '1.0'
  x-logo:
    url: https://logo.clearbit.com/openlayer.com
servers:
  - url: https://api.openlayer.com/v1
    description: Our prod backend
security:
  - bearerAuth: []
paths:
  /background-tasks/{taskId}:
    get:
      tags:
        - Background Tasks
      summary: Retrieve a background task
      description: >
        Retrieve a background task's status, progress and results.


        Endpoints that cannot answer within one request queue a task and hand
        back its id -- for example

        `POST /frameworks/{frameworkId}/export`. Poll this endpoint until
        `complete` is `true`, then read

        what the task produced from `outputs`.
      operationId: getBackgroundTaskById
      parameters:
        - $ref: '#/components/parameters/taskId'
      responses:
        '200':
          description: Status OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackgroundTask'
        default:
          $ref: '#/components/responses/UnexpectedError'
      x-codeSamples:
        - lang: curl
          source: |
            curl --request GET \
              --url https://api.openlayer.com/v1/background-tasks/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
              --header 'Authorization: Bearer <token>'
components:
  parameters:
    taskId:
      name: taskId
      in: path
      description: The background task id.
      required: true
      schema:
        type: string
        format: uuid
  schemas:
    BackgroundTask:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: The background task id.
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        name:
          type: string
          readOnly: true
          description: >-
            The task's internal name, including the arguments it was queued
            with.
          example: >-
            ExportFrameworkRunner(framework_id=9f1b3c2d-4e5a-4f60-8a71-2b3c4d5e6f70,
            project_id=None)
        progress:
          type: number
          format: float
          minimum: 0
          maximum: 100
          description: How far along the task is, from 0 to 100.
          example: 95
        complete:
          type: boolean
          description: Whether the task has finished. Check this before reading `outputs`.
        error:
          type: string
          nullable: true
          description: Why the task failed, or `null` if it has not failed.
        outputs:
          type: object
          nullable: true
          description: >
            Whatever the task produced, keyed by name. `null` until the task
            completes. A framework export returns `storageUri` -- pass it to
            `GET /storage/presigned-url` to download the archive -- along with
            `filename`, `controlCount`, `evidenceCount` and
            `missingEvidenceCount`.
          example:
            storageUri: s3://openlayer-storage/exports/soc2-2026-09-15.zip
            filename: soc2-2026-09-15.zip
            controlCount: 64
            evidenceCount: 51
            missingEvidenceCount: 13
        dateCreated:
          type: string
          format: date-time
          readOnly: true
          description: When the task was queued.
          example: '2026-09-15T11:31:01.185Z'
        dateUpdated:
          type: string
          format: date-time
          readOnly: true
          description: When the task last reported progress.
          example: '2026-09-15T11:33:47.902Z'
      required:
        - id
        - name
        - progress
        - complete
        - dateCreated
        - dateUpdated
  responses:
    UnexpectedError:
      description: Unexpected error.
      content:
        application/json:
          schema:
            type: object
            required:
              - code
              - error
            properties:
              code:
                type: integer
                format: int32
              error:
                type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        Bearer authentication header of the form `Bearer <token>`, where
        `<token>` is your workspace API key. See [Find your API
        key](https://www.openlayer.com/docs/workspace-and-projects/find-your-api-key)
        for more information.

````