Skip to main content
GET
Get Ingest Job
← How Bulk Ingestion Works Read the status, counters and progress of a job created by a bulk endpoint such as POST /v2/wastes or the POST /v2/invoices/* routes. This is the endpoint to poll while the records are being calculated (or deleted); the ingest_job.finished webhook tells you when it ends without polling.
Beta. Part of the bulk ingest API, in beta. The contract may still change before general availability.

Request

Headers

string
required
Your API key (see Authentication).Example: ${DCYCLE_API_KEY}
string
required
UUID of the organization that created the job, or of one of its parent organizations.Example: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Path Parameters

uuid
required
The job id, as returned in the bulk response body and in its Location header.Example: 2d4b90c1-7c1e-4b6f-9a55-3f2b8e61d0aa

Response

uuid
Job id.
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: treat every status other than processing as finished. A job whose chunks_done stops moving for 4 hours is closed completed_with_errors: see A job that does not finish.
string
What the job creates, updates or deletes: one of the values in Entity types; the routes table gives the routes of each.
string
Available values: create, update (Classify Purchase Suppliers, Replace Commuting Response (v2)), delete (e.g. Delete Wastes, Delete Invoices).
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), survey by an employee answering the commuting survey (its email or its QR code). Only api_bulk jobs send the ingest_job.finished webhook. file_upload and import_wizard are reserved.
object
integer
Number of calculation chunks.
integer
Chunks already calculated. chunks_done / chunks_total is the progress. The job of a synchronous create is born completed with 0 of 0 chunks and sends no webhook.
datetime
When the job was created (UTC).
datetime | null
When the job finished (UTC), null while it is processing.
object
self: this job. items: its per-record outcomes.

Example

Successful Response

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. A synchronous create (201) has nothing to poll: its job is born completed with 0 of 0 chunks and sends no webhook.
Rather not poll? Register a webhook endpoint for ingest_job.finished: Dcycle sends you this same object, signed, as soon as the job finishes.

A job that does not finish

chunks_done normally moves within minutes. A record whose calculation fails unexpectedly (for example, emissions too large to store) does not hold the others: its item ends failed and the rest of its chunk goes on (when several records of a chunk fail, it can take about 15 minutes more). A chunk whose every record fails unexpectedly is retried once, about 15 minutes later, in case the error is temporary; then its records end failed (CALCULATION_FAILED, or DELETE_FAILED in a delete job) and the job finishes. A job whose chunks_done has not changed for 4 hours is stuck, and Dcycle closes it (it checks every hour, so within 5 hours; a chunk being calculated at that moment finishes first, and the 4 hours start again): the records still pending end failed with JOB_TIMED_OUT, and the job ends completed_with_errors and sends its ingest_job.finished webhook like any other. So a job always finishes, and its webhook always arrives. What to do with a JOB_TIMED_OUT record depends on the job:
  • Create: the record is stored without emissions. Contact support with the job id. Do not resend the batch with a new Idempotency-Key: its records are already stored, so you would duplicate them.
  • Delete: the record was not deleted. Send its id in a new delete job; if that fails too, contact support with the job id. A vehicle or a facility is hidden as soon as its delete is accepted, so a new delete request that includes it is rejected whole (422 BULK_RECORDS_REJECTED, NOT_FOUND on its id): leave it out and contact support with the job id.
  • Update (PATCH /v2/purchases/suppliers, PUT /v2/employees/commuting/responses/{response_id}): the change is stored, but the emissions were not calculated again (the supplier’s purchases may keep the emissions of its previous code; the response’s changed periods have none). Send the same change again with a new Idempotency-Key to calculate them; for a commuting response, send the PUT to its item’s entity_id, its response_id after the change.

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.

List Ingest Job Items

Per-record outcomes of the job

Create Wastes (v2)

Create up to 5,000 wastes in one request

Invoices API

Create up to 5,000 invoices of a category in one request