List Ingest Job Items

Per-record outcomes of a bulk ingest job, in submission order

GET /v2/ingest-jobs/{job_id}/items

List Ingest Job Items

JavaScript

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));

200

{
  "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
}

← Create Wastes (v2)

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 (entity_id).

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

Request

Headers

x-api-key · string · required

Your API key for authentication

Example: sk_live_1234567890abcdef

x-organization-id · 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

job_id · uuid · required

The job id.

Example: 2d4b90c1-7c1e-4b6f-9a55-3f2b8e61d0aa

Query Parameters

status · string

Only items with this outcome.

Available values: pending, succeeded, failed (skipped is reserved: no item ends in it today)

Example: failed

stage · string

Only items at this stage.

Available values: persist, calculate, delete

Example: calculate

page · integer · default: "1"

Page number, starting at 1.

size · integer · default: "10"

Items per page, between 1 and 500.

Response

items · array[object]

Show item fields

source_row_index · integer

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

client_row_id · string | null

The client_row_id you sent with the record.

chunk_index · integer | null

Calculation chunk the record belongs to.

stage · string

Where the record is, or where it failed. Available values: persist (stored, nothing to calculate), calculate (stored, emissions calculated or being calculated), delete (a delete job: deleted or being deleted).

status · string

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

entity_id · uuid | null

Id of the entity created from the record, e.g. the waste id. For a record split across facilities, the id of the first waste of the group (the group shares it as source_waste_id).

error_code · 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 waste was already gone when its chunk ran.

error_params · object | null

Values that explain the error, when available. CALCULATION_FAILED does not carry the reason yet (null): see Why a record failed to calculate.

attempt_count · integer

How many times the record’s calculation ran.

total · integer

Number of items matching the filters.

page · integer

Current page.

size · integer

Page size.

Example

cURL

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}"

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 waste was stored, it just has no emissions. Read it with Get Waste: status: "error" when no factor covers its LER/R/D codes or it has no unit, status: "review" when its description matched no factor.

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.

Related Endpoints

Get Ingest Job

Status and progress of the job

Create Wastes (v2)

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