List Ingest Job Items

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v2/ingest-jobs/{job_id}/items', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v2/ingest-jobs/{job_id}/items"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "items": {
    "source_row_index": 123,
    "client_row_id": {},
    "chunk_index": {},
    "stage": "<string>",
    "status": "<string>",
    "entity_id": {},
    "error_code": {},
    "error_params": {},
    "attempt_count": 123
  },
  "total": 123,
  "page": 123,
  "size": 123
}

GET

ingest-jobs

{job_id}

items

List Ingest Job Items

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v2/ingest-jobs/{job_id}/items', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v2/ingest-jobs/{job_id}/items"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "items": {
    "source_row_index": 123,
    "client_row_id": {},
    "chunk_index": {},
    "stage": "<string>",
    "status": "<string>",
    "entity_id": {},
    "error_code": {},
    "error_params": {},
    "attempt_count": 123
  },
  "total": 123,
  "page": 123,
  "size": 123
}

← How Bulk Ingestion Works One item per submitted record, in the order the records were sent. Use it to find which records failed to calculate and why, and to map each record (by source_row_index or your client_row_id) to the entity that was created or, in the reuse stage, matched (entity_id).

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.Example: 2d4b90c1-7c1e-4b6f-9a55-3f2b8e61d0aa

Query Parameters

string

Only items with this outcome.Available values: pending, succeeded, failed (skipped is reserved)Example: failed

string

Only items at this stage.Available values: persist, reuse, calculate, deleteExample: calculate

integer

default:"1"

Page number, starting at 1.

integer

default:"10"

Items per page, between 1 and 500.

Response

array[object]

Show item fields

integer

Position of the record in the submitted records array, starting at 0.

string | null

The client_row_id you sent with the record.

integer | null

Calculation chunk the record belongs to.

string

Where the record is, or where it failed. Available values: persist (stored, nothing to calculate), reuse (nothing written: the record matched an employee who already existed, whose id is entity_id; see on_existing=reuse), calculate (stored, emissions calculated or being calculated), delete (a delete job, e.g. Delete Invoices: deleted or being deleted).

string

Available values: pending (waiting for its chunk), succeeded, failed. skipped is reserved.

uuid | null

Id of the entity created from the record (in a delete job, the one deleted; in the reuse stage, the existing one the record matched), e.g. the waste or invoice id. For a record split across facilities, the id of the first facility’s entity; the others share it as source_invoice_id (wastes and invoices alike).

string | null

What failed, when status is failed. CALCULATION_FAILED: the entity was stored but its emissions could not be calculated. DELETE_FAILED: in a delete job, the entity was already gone when its chunk ran, or it could not be deleted: if it still exists, send its id in a new delete job, and if that fails too (or for a vehicle or a facility, which a new delete job cannot reach), contact support with the job id. JOB_TIMED_OUT: the job made no progress for 4 hours and was closed with this record still pending (A job that does not finish). In Classify Purchase Suppliers, CALCULATION_FAILED or EXCHANGE_RATE_NOT_FOUND with purchases_failed means the supplier keeps its new code and some of its purchases ended in error. A route may give the reason with codes of its own instead: logistics legs (Why a leg failed to calculate), purchases (Why a purchase failed), business travels (How it works), freight transports (How it works) and commuting responses (How it works).

object | null

Values that explain the error, when the route’s code has them (e.g. error_params.message for a logistics leg, field and message for the section of a freight transport that failed, or purchases_failed for a purchase supplier whose purchases ended in error). Otherwise CALCULATION_FAILED comes with null: see Why a record failed to calculate for wastes; for invoices, the usual causes are a unit the fuel is not calculated in (see which unit to send) or one your custom factor cannot convert from.

integer

How many times the record’s calculation ran.

integer

Number of items matching the filters.

integer

Current page.

integer

Page size.

Example

curl "https://api.dcycle.io/v2/ingest-jobs/2d4b90c1-7c1e-4b6f-9a55-3f2b8e61d0aa/items?status=failed&size=500" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

import os

import requests

url = "https://api.dcycle.io/v2/ingest-jobs/2d4b90c1-7c1e-4b6f-9a55-3f2b8e61d0aa/items"
headers = {
    "x-api-key": os.environ["DCYCLE_API_KEY"],
    "x-organization-id": os.environ["DCYCLE_ORG_ID"],
}

page = 1
while True:
    body = requests.get(url, headers=headers, params={"status": "failed", "size": 500, "page": page}, timeout=30).json()
    for item in body["items"]:
        print(item["source_row_index"], item["client_row_id"], item["entity_id"], item["error_code"])
    if page * body["size"] >= body["total"]:
        break
    page += 1

const axios = require('axios');

const { data } = await axios.get(
  'https://api.dcycle.io/v2/ingest-jobs/2d4b90c1-7c1e-4b6f-9a55-3f2b8e61d0aa/items',
  {
    params: { status: 'failed', size: 500 },
    headers: {
      'x-api-key': process.env.DCYCLE_API_KEY,
      'x-organization-id': process.env.DCYCLE_ORG_ID,
    },
  },
);
data.items.forEach(item => console.log(item.client_row_id, item.error_code));

Successful Response

{
  "items": [
    {
      "source_row_index": 88,
      "client_row_id": "ALB-2026-09-0089",
      "chunk_index": 0,
      "stage": "calculate",
      "status": "failed",
      "entity_id": "6a0c1f3e-2b7d-4c8e-9f10-4d5e6a7b8c9d",
      "error_code": "CALCULATION_FAILED",
      "error_params": null,
      "attempt_count": 1
    }
  ],
  "total": 1,
  "page": 1,
  "size": 500
}

A failed item of a create job still has an entity_id: the record was stored, it just has no emissions.

A waste: read it with Get Waste. status: "error" when no factor covers its LER/R/D codes, status: "review" when its description matched no factor.
An invoice: it stays with status: "error"; find it with List Invoices, fix it with Update Invoice or delete it and send it again.

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.

422 Validation Error

An unknown status or stage value, or size outside 1 to 500.

Get Ingest Job

Status and progress of the job

Create Wastes (v2)

Create one or up to 5,000 wastes in one request

Invoices API

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

Request

Headers

Path Parameters

Query Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

404 Not Found

422 Validation Error

Related Endpoints

Get Ingest Job

Create Wastes (v2)

Invoices API