Get Job Run Image Pull Progress

Deprecated. Consumers can read image_pull on GET /v1/job-runs/{uuid} instead: it carries the same progress plus a status of pending, pulling, complete, failed or unknown. Both routes require a consumer-visible role and either job ownership or job_runs.read.all for image pull progress. This route retains its snapshot response shape until the date in the Sunset response header, then the path is reserved for a Job Run lifecycle event list. Responses carry Deprecation and Sunset headers.

Check Docker image pull progress while a Job Run prepares to start. Get the run’s UUID from GET /v1/job-runs.

Read progress

Call GET /v1/job-runs/{uuid}/events. Poll this endpoint while the run is preparing to get updated progress. Each request returns the latest snapshot as JSON, not a list of events or a live stream.

Response

• download_percentage: the estimated download percentage, from 0 to 100. Null when the total download size is not known.
• speed_bytes_per_sec: the estimated recent download speed in bytes per second. Null when there are not enough samples to calculate it.
• latest: the latest reported image pull event, including downloaded bytes and any available image details. Null when no event is available. This response does not include node_uuid.

Before the first progress event, the response is {"download_percentage":null,"latest":null,"speed_bytes_per_sec":null}. A null value means information is unavailable, not that the pull failed.

For container output after startup, use GET /v1/job-runs/{uuid}/container-logs.

Access

Sign requests with your API key and HMAC headers. You need a consumer-visible role (SERVICE_CONSUMER, ADMIN, STAFF or OPS) and either job_runs.read.own for a job you created or job_runs.read.all for any run. Operating the assigned node does not grant access, including for dual-role accounts reading another consumer’s job. Operator-only callers and callers without access receive 404. This intentionally removes legacy operator access to private image references and pull errors. No node read permission is required.

GET /v1/job-runs/{uuid}/events

Get Job Run Image Pull Progress

cURL

curl --request GET \
  --url https://api.dispersed.com/v1/job-runs/{uuid}/events

200

{
  "download_percentage": 50,
  "latest": {
    "client_observed_at_ms": 1793750400000,
    "created_at": "2026-11-04T00:00:00.000Z",
    "job_run_uuid": "11111111-1111-4111-8111-111111111111",
    "object": "node_event",
    "payload": {
      "downloaded_bytes": 52428800,
      "image": "library/ubuntu",
      "tag": "latest",
      "total_bytes": 104857600
    },
    "schema_version": 1,
    "server_received_at_ms": 1793750400100,
    "type": "DOCKER_IMAGE_PULL_PROGRESS",
    "uuid": "22222222-2222-4222-8222-222222222222"
  },
  "speed_bytes_per_sec": 1048576
}

Path Parameters

uuid · string<uuid> · required

Response

200

application/json

The latest image pull progress, or null fields if no progress is available.

download_percentage · number | null · required

Estimated image download percentage, from 0 to 100. Null when the total download size is not known.

latest · object | null · required

The latest image pull event, or null if none is available. type is DOCKER_IMAGE_PULL_PROGRESS. Inside payload, downloaded_bytes is the number of bytes downloaded so far. Optional fields include total_bytes (expected download size), image, tag, docker_status, and error_message. Other payload fields may be added. The event does not include node_uuid.

Show child attributes

speed_bytes_per_sec · number | null · required

Estimated recent download speed in bytes per second. Null when there are not enough valid progress samples to calculate a speed.