---
title: "List batch jobs"
method: GET
path: "/jobs"
tags: ["jobs"]
---

# List batch jobs

`GET /jobs`

Returns batch job definitions in the workspace. Each job can be triggered to run multiple parallel tasks with configurable concurrency and retry settings. Starting with API version 2026-04-28 the response is wrapped in `{data, meta}` and supports cursor pagination via the `cursor` and `limit` query parameters; older versions keep returning a bare array with all jobs.

## Query parameters

- `cursor` string
- `limit` integer
- `sort` 'createdAt:desc' | 'createdAt:asc' | 'name:asc' | 'name:desc'
- `q` string
- `anchor` 'end'

## Response `200`

successful operation

- JobList — Cursor-paginated list of batch jobs. Returned starting with API version 2026-04-28; older API versions return a bare array.
  - `data` Job[] — Page of jobs.
    - `events` CoreEvent[] — Events happening on a resource deployed on Blaxel
      - `canaryRevision` string — Canary revisionID link to the event
      - `message` string — Event message
      - `revision` string — RevisionID link to the event
      - `status` string — Event status
      - `time` string — Event time
      - `type` string — Event type
    - `metadata` Metadata, required — Owner fields for Persistence
      - `createdAt` string — The date and time when the resource was created
      - `updatedAt` string — The date and time when the resource was updated
      - `createdBy` string — The user or service account who created the resource
      - `updatedBy` string — The user or service account who updated the resource
      - `displayName` string — Human-readable name for display in the UI. Can contain spaces and special characters, max 63 characters.
      - `externalId` string — Caller-owned identifier for external lookups. Max 64 chars, alphanumeric + dash.
      - `labels` MetadataLabels — Key-value pairs for organizing and filtering resources. Labels can be used to categorize resources by environment, project, team, or any custom taxonomy.
      - `name` string, required — Unique identifier for the resource within the workspace. Must be lowercase alphanumeric with hyphens, max 49 characters. Immutable after creation.
      - `plan` string — Billing plan tier applied to this resource (inherited from workspace account)
      - `url` string — Auto-generated endpoint URL for accessing this resource (for agents, functions, models, sandboxes)
      - `workspace` string — Name of the workspace this resource belongs to (read-only, set automatically)
    - `spec` JobSpec, required — Configuration for a batch job including execution parameters, parallelism settings, and deployment region
      - `enabled` boolean — When false, the job is disabled and new executions cannot be triggered
      - `githubRunner` GithubRunnerConfig — Configuration for running GitHub Actions workflow jobs on Blaxel infrastructure. When repositories are configured, the job acts as a self-hosted GitHub Actions runner. Workflow jobs use runs-on with the Blaxel job name to target a specific runner.
        - `repositories` string[] — Repositories in owner/repo format that this runner is associated with. The runner will pick up workflow jobs from any of these repositories. If non-empty, the runner is considered enabled.
      - `policies` string[]
      - `region` string — Region where the job should be created (e.g. us-was-1, eu-lon-1)
      - `revision` RevisionConfiguration — Revision configuration
        - `active` string — Active revision id
        - `canary` string — Canary revision id
        - `canaryPercent` integer — Canary revision percent
        - `stickySessionTtl` integer — Sticky session TTL in seconds (0 = disabled)
        - `traffic` integer — Traffic percentage
      - `runtime` JobRuntime — Runtime configuration defining how batch job tasks are executed with parallelism and retry settings
        - `diskPercent` integer — Percentage of VM RAM allocated for disk storage (tmpfs overlay). Valid range 10-95, default 50. Only applies to mk3.1 (microVM) generation.
        - `envs` Env[] — Environment variables injected into job tasks. Supports Kubernetes EnvVar format with valueFrom references.
          - `name` string — Name of the environment variable
          - `secret` boolean — Whether the value is a secret
          - `value` string — Value of the environment variable
        - `generation` 'mk2' | 'mk3' — Infrastructure generation: mk2 (containers, 2-10s cold starts) or mk3 (microVMs, sub-25ms cold starts)
        - `image` string — Container image built by Blaxel when deploying with 'bl deploy'. This field is auto-populated during deployment.
        - `maxRetries` integer — Number of automatic retry attempts for failed tasks before marking as failed
        - `memory` integer — Memory allocation in megabytes. Also determines CPU allocation (CPU cores = memory in MB / 2048, e.g., 4096MB = 2 CPUs).
        - `ports` Port[] — Set of ports for a resource
          - `name` string — The name of the port
          - `protocol` 'HTTP' | 'TCP' | 'UDP' | 'TLS' — The protocol of the port
          - `target` integer, required — The target port of the port
        - `timeout` integer — Maximum execution time in seconds before a task is terminated
      - `triggers` Trigger[] — Triggers to use your agent
        - `configuration` TriggerConfiguration — Trigger configuration
          - `authenticationType` string — The authentication type of the trigger
          - `callbackSecret` string — The callback secret for async triggers (auto-generated, encrypted)
          - `callbackUrl` string — The callback URL for async triggers (optional)
          - `path` string — The path of the trigger
          - `retry` integer — The retry of the trigger
          - `schedule` string — The schedule of the trigger, cron expression * * * * *
          - `tasks` TriggerConfigurationTask[] — The tasks configuration of the cronjob
          - `timeout` integer — The timeout in seconds for async triggers (max 900s, MK3 only)
        - `enabled` boolean — Enable or disable the trigger (default: true)
        - `id` string — Identifier of the trigger. Optional — the server auto-generates a unique id when one is not provided, and disambiguates duplicates within a resource.
        - `type` 'http' | 'http-async' | 'cron' — The type of trigger, can be http or http-async
      - `volumes` JobVolume[]
        - `mountPath` string, required — Absolute filesystem path where the volume will be mounted inside the container
        - `name` string, required — Identifier for the volume, used to reference it internally
        - `readOnly` boolean — If true, the volume is mounted read-only
        - `sizeMb` integer, required — Storage capacity in megabytes
        - `type` 'ephemeral', required — Type of volume. Currently only "ephemeral" is supported.
    - `status` 'DELETING' | 'TERMINATED' | 'FAILED' | 'DEACTIVATED' | 'DEACTIVATING' | 'UPLOADING' | 'BUILDING' | 'DEPLOYING' | 'DEPLOYED' | 'BUILT' — Deployment status of a resource deployed on Blaxel
  - `meta` PaginationMeta — Pagination metadata returned alongside a page of listing results. Always present on listing endpoints starting with API version 2026-04-28.
    - `hasMore` boolean — True when more pages are available beyond the current one.
    - `nextCursor` string — Opaque cursor to pass back as the `cursor` query param for the next page. Empty when there are no more pages.
    - `total` integer — Total number of items in the workspace, ignoring the current page's filters. Lets the UI render "page X of Y" without walking the cursor chain. Computed from the hash-only metadata.workspace GSI count, so search (`q`) does not narrow it.

---

[API](https://skmtc.net/blaxel/apis/blaxel-control-plane.md) · [All operations](https://skmtc.net/blaxel/apis/blaxel-control-plane/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/blaxel/blaxel-control-plane/revisions/dfa264bc72ee/schema)