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

# Get Ingest Job

> Status and progress of a bulk ingest job

[← Create Wastes (v2)](/api-reference/wastes/create-v2)

Read the status, counters and progress of a job created by a bulk endpoint such as
[`POST /v2/wastes`](/api-reference/wastes/create-v2). This is the endpoint to poll while the records are being
calculated.

<Warning>
  **Beta.** Part of the bulk ingest API, currently in beta. The contract may still change before general
  availability.
</Warning>

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication

  **Example:** `sk_live_1234567890abcdef`
</ParamField>

<ParamField header="x-organization-id" type="string" required>
  UUID of the organization that created the job, or of one of its parent organizations.

  **Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`
</ParamField>

### Path Parameters

<ParamField path="job_id" type="uuid" required>
  The job `id`, as returned in the bulk response body and in its `Location` header.

  **Example:** `2d4b90c1-7c1e-4b6f-9a55-3f2b8e61d0aa`
</ParamField>

## Response

<ResponseField name="id" type="uuid">
  Job id.
</ResponseField>

<ResponseField name="status" type="string">
  **Available values:** `processing`, `completed`, `completed_with_errors`.

  * `processing`: the job is running: records are being calculated (or deleted, in a delete job).
  * `completed`: every record succeeded.
  * `completed_with_errors`: every chunk ran and at least one record failed (`counts.failed > 0`).

  `failed` is reserved and no job ends in it today. A job whose `chunks_done` stops moving stays `processing`:
  see [A job that does not finish](#a-job-that-does-not-finish).
</ResponseField>

<ResponseField name="entity_type" type="string">
  What the job creates, e.g. `wastes`.
</ResponseField>

<ResponseField name="operation" type="string">
  **Available values:** `create`, `delete` ([Delete Wastes](/api-reference/wastes/delete-v2)).
</ResponseField>

<ResponseField name="source" type="string">
  How the job was submitted: `api_bulk` with an API key (an integration), `app` by a person signed in to Dcycle (the
  app's forms, or tools that act on their session). Only `api_bulk` jobs send the
  [`ingest_job.finished` webhook](/api-reference/webhooks/overview#events). `file_upload` and `import_wizard` are
  reserved.
</ResponseField>

<ResponseField name="counts" type="object">
  <Expandable title="fields">
    <ResponseField name="submitted" type="integer">Records (or ids, in a delete job) in the request.</ResponseField>

    <ResponseField name="succeeded" type="integer">
      Records already processed: calculated in a create job, deleted in a delete job.
    </ResponseField>

    <ResponseField name="failed" type="integer">
      Records that could not be processed. In a create job the record exists but has no emissions; in a delete job
      the waste was already gone. The [job's items](/api-reference/ingest-jobs/list-items) say which ones.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="chunks_total" type="integer">
  Number of calculation chunks.
</ResponseField>

<ResponseField name="chunks_done" type="integer">
  Chunks already calculated. `chunks_done / chunks_total` is the progress.
</ResponseField>

<ResponseField name="created_at" type="datetime">
  When the job was created (UTC).
</ResponseField>

<ResponseField name="finished_at" type="datetime | null">
  When the job finished (UTC), `null` while it is processing.
</ResponseField>

<ResponseField name="links" type="object">
  `self`: this job. `items`: [its per-record outcomes](/api-reference/ingest-jobs/list-items).
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl "https://api.dcycle.io/v2/ingest-jobs/2d4b90c1-7c1e-4b6f-9a55-3f2b8e61d0aa" \
    -H "x-api-key: ${DCYCLE_API_KEY}" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os

  import requests

  job = requests.get(
      "https://api.dcycle.io/v2/ingest-jobs/2d4b90c1-7c1e-4b6f-9a55-3f2b8e61d0aa",
      headers={
          "x-api-key": os.environ["DCYCLE_API_KEY"],
          "x-organization-id": os.environ["DCYCLE_ORG_ID"],
      },
      timeout=30,
  ).json()
  print(job["status"], f"{job['chunks_done']}/{job['chunks_total']}")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const axios = require('axios');

  const { data: job } = await axios.get(
    'https://api.dcycle.io/v2/ingest-jobs/2d4b90c1-7c1e-4b6f-9a55-3f2b8e61d0aa',
    {
      headers: {
        'x-api-key': process.env.DCYCLE_API_KEY,
        'x-organization-id': process.env.DCYCLE_ORG_ID,
      },
    },
  );
  console.log(job.status, `${job.chunks_done}/${job.chunks_total}`);
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "2d4b90c1-7c1e-4b6f-9a55-3f2b8e61d0aa",
  "status": "completed_with_errors",
  "entity_type": "wastes",
  "operation": "create",
  "source": "api_bulk",
  "counts": { "submitted": 250, "succeeded": 247, "failed": 3 },
  "chunks_total": 3,
  "chunks_done": 3,
  "created_at": "2026-09-29T10:15:02.184Z",
  "finished_at": "2026-09-29T10:16:41.902Z",
  "links": {
    "self": "/v2/ingest-jobs/2d4b90c1-7c1e-4b6f-9a55-3f2b8e61d0aa",
    "items": "/v2/ingest-jobs/2d4b90c1-7c1e-4b6f-9a55-3f2b8e61d0aa/items"
  }
}
```

<Tip>
  Poll every 5 to 10 seconds and stop when `status` is no longer `processing`. `chunks_done / chunks_total` tells
  you how far along the job is.
</Tip>

<Tip>
  Rather not poll? Register a [webhook endpoint](/api-reference/webhooks/overview) for `ingest_job.finished`: Dcycle
  sends you this same object, signed, as soon as the job finishes.
</Tip>

### A job that does not finish

`chunks_done` normally moves within minutes. If it has not changed for 30 minutes, the job is stuck: Dcycle does not
retry it on its own yet, and its `ingest_job.finished` webhook will not arrive. Contact support with the job `id`. Do
not resend a create batch with a new `Idempotency-Key`: its records are already stored, so you would duplicate them.

## Common Errors

### 401 Unauthorized

Missing or invalid API key.

### 404 Not Found

The job does not exist, or it belongs to an organization outside the one in `x-organization-id`. Both cases return
the same response.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "https://code.dcycle.io/api-reference/errors#NOT_FOUND",
  "title": "Not Found",
  "status": 404,
  "code": "NOT_FOUND",
  "detail": "IngestJobModel with id='2d4b90c1-7c1e-4b6f-9a55-3f2b8e61d0aa' not found",
  "request_id": "b2248a31-0f1b-4a7d-83ce-b29bd5977b4c"
}
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="List Ingest Job Items" icon="list" href="/api-reference/ingest-jobs/list-items">
    Per-record outcomes of the job
  </Card>

  <Card title="Create Wastes (v2)" icon="plus" href="/api-reference/wastes/create-v2">
    Create up to 5,000 wastes in one request
  </Card>
</CardGroup>


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