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

# Retrieve a background task

> Retrieve a background task's status and 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 and 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: python
          source: >
            from openlayer import Openlayer


            client = Openlayer()


            task =
            client.background_tasks.retrieve("1e2f3a4b-5c6d-4e7f-9a8b-0c1d2e3f4a5b")

            print(task.complete, task.progress)
        - lang: typescript
          source: >
            import Openlayer from 'openlayer';


            const client = new Openlayer();


            const task = await
            client.backgroundTasks.retrieve('1e2f3a4b-5c6d-4e7f-9a8b-0c1d2e3f4a5b');


            console.log(task.complete);
        - lang: go
          source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/openlayer-ai/openlayer-go\"\n)\n\nclient := openlayer.NewClient()\ntask, err := client.BackgroundTasks.Get(context.TODO(), \"1e2f3a4b-5c6d-4e7f-9a8b-0c1d2e3f4a5b\")\nif err != nil {\n\tpanic(err.Error())\n}\nfmt.Printf(\"%+v\\n\", task.Complete)\n"
        - lang: java
          source: >
            import com.openlayer.api.client.OpenlayerClient;

            import com.openlayer.api.client.okhttp.OpenlayerOkHttpClient;

            import
            com.openlayer.api.models.backgroundtasks.BackgroundTaskRetrieveResponse;


            OpenlayerClient client = OpenlayerOkHttpClient.fromEnv();


            BackgroundTaskRetrieveResponse task =
            client.backgroundTasks().retrieve("1e2f3a4b-5c6d-4e7f-9a8b-0c1d2e3f4a5b");
        - lang: ruby
          source: >
            require "openlayer"


            openlayer = Openlayer::Client.new(api_key: ENV["OPENLAYER_API_KEY"])


            task =
            openlayer.background_tasks.retrieve("1e2f3a4b-5c6d-4e7f-9a8b-0c1d2e3f4a5b")


            puts(task)
        - 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
      description: >
        A job queued by an endpoint that can't answer within one request, such
        as a framework export. Poll it until `complete` is `true`, then read
        what it produced from `outputs`.
      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.

````

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