---
title: "Check the status of a batch job"
method: GET
path: "/cpf/bulk/{jobId}"
tags: ["Bulk"]
---

# Check the status of a batch job

`GET /cpf/bulk/{jobId}`

Returns progress, counts, and per-CPF results for a batch job created via `POST /cpf/bulk`. Poll this endpoint until `data.status` is `done` or `failed`.

- `data.cpfs` contains one object per processed CPF, enriched from the local database for `found: true` rows (same fields as `GET /cpf/{cpf}`).
- While `status` is `processing`, `data.cpfs` reflects only what has been persisted so far and grows on each poll.
- `skipped` CPFs (not processed due to insufficient credits) never appear in `data.cpfs`.
- Unlike `GET /cpf/{cpf}`, the `cpf` field inside `data.cpfs` is **not** formatted (plain 11 digits, no punctuation).

## Path parameters

- `jobId` string, uuid, required

## Response `200`

Job status returned successfully

- BulkStatusResponse — Aggregate status of a batch job
  - `success` boolean, required
  - `data` object, required
    - `id` string, uuid
    - `status` 'processing' | 'done' | 'failed'
    - `file_name` string, nullable
    - `format` string, nullable
    - `total_records` integer
    - `processed` integer
    - `found` integer — Consumes 1 credit each
    - `not_found` integer — Does not consume credits
    - `skipped` integer — Not processed due to insufficient credits
    - `error` string, nullable
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `cpfs` BulkResultItem[] — Per-CPF results, populated incrementally as the job processes. Skipped CPFs never appear here.
      - `cpf` string, required — Unformatted CPF (11 digits, no punctuation) — unlike GET /cpf/{cpf}
      - `found` boolean, required — Whether the CPF was found in the database (consumes 1 credit)
      - `name` string, nullable, required
      - `nameUpper` string, nullable, required
      - `gender` 'M' | 'F' | 'null', nullable, required
      - `birthDate` string, nullable, required
      - `day` integer, nullable, required
      - `month` integer, nullable, required
      - `year` integer, nullable, required

## Other responses

- `401` — Missing or invalid API Key
- `404` — Job not found or does not belong to your account

---

[API](https://skmtc.net/cpfhub/apis/cpfhub-io-api.md) · [All operations](https://skmtc.net/cpfhub/apis/cpfhub-io-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cpfhub/cpfhub-io-api/versions/0aa1f2b175ff/schema)