> ## 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 Logistics Packages (v2)

> Read up to 100 packages by id, with their current distance and emissions totals

[← Logistics API](https://code.dcycle.io/api-reference/logistics/overview.md)

Read packages (parcels) by their Dcycle id, up to 100 per request, with the totals of their legs. Use it after a load
to get the footprint of the packages it touched: one request per 100 packages instead of one per package.

> [!WARNING]
>
> **Beta.** Part of the v2 logistics API, in beta. The contract may still change before general availability.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -G "https://api.dcycle.io/v2/logistics/packages" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  --data-urlencode "id=3f2a1b0c-9d8e-4f7a-8b6c-5d4e3f2a1b0c" \
  --data-urlencode "id=4a3b2c1d-0e9f-4a8b-9c7d-6e5f4a3b2c1d"
```

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

import requests

package_ids = ["3f2a1b0c-9d8e-4f7a-8b6c-5d4e3f2a1b0c", "4a3b2c1d-0e9f-4a8b-9c7d-6e5f4a3b2c1d"]
response = requests.get(
    "https://api.dcycle.io/v2/logistics/packages",
    headers={
        "x-api-key": os.environ["DCYCLE_API_KEY"],
        "x-organization-id": os.environ["DCYCLE_ORG_ID"],
    },
    params=[("id", package_id) for package_id in package_ids],  # up to 100 per request
    timeout=60,
)
response.raise_for_status()
for package in response.json()["items"]:
    print(package["package_key"], package["total_co2e"])
```

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

const packageIds = ['3f2a1b0c-9d8e-4f7a-8b6c-5d4e3f2a1b0c', '4a3b2c1d-0e9f-4a8b-9c7d-6e5f4a3b2c1d'];
const params = new URLSearchParams(packageIds.map((id) => ['id', id])); // up to 100 per request
const { data } = await axios.get(`https://api.dcycle.io/v2/logistics/packages?${params}`, {
  headers: {
    'x-api-key': process.env.DCYCLE_API_KEY,
    'x-organization-id': process.env.DCYCLE_ORG_ID,
  },
});
data.items.forEach((pkg) => console.log(pkg.package_key, pkg.total_co2e));
```

```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    {
      "id": "3f2a1b0c-9d8e-4f7a-8b6c-5d4e3f2a1b0c",
      "package_key": "PKG-000123",
      "shipment_id": "SHIP-0042",
      "client_billing_id": null,
      "weight_kg": 2.3,
      "total_distance_km": 812.0,
      "total_co2e": 0.287,
      "status": "active",
      "created_at": "2026-11-03T22:26:04.472Z",
      "updated_at": "2026-11-04T09:10:00.000Z"
    }
  ],
  "not_found": ["4a3b2c1d-0e9f-4a8b-9c7d-6e5f4a3b2c1d"]
}
```

## How it works

* **Each package comes once, in the order of the ids.** An id repeated in the request is read once.
* **An id with no package in your organization is listed in `not_found`, not an error.** An unknown id and another
  organization's answer the same.
* **The totals follow the legs.** `total_distance_km` and `total_co2e` are summed over the package's active legs and
  recalculated after its legs are written or deleted. A package whose legs arrive in several loads changes as they
  arrive: read it again after a later load. To know whether it changed, compare its `updated_at` with the value you
  last read (not with your own clock). A recalculation that fails is repaired the next time one of its legs is
  written, and a revision of a TOC's emission factor shows on the next write of one of its legs.
* `total_co2e` is in kg CO₂e: each leg's tonne-km times its TOC's well-to-wheel factor, own-fleet legs included (the
  [logistics report](https://code.dcycle.io/api-reference/logistics/get-report.md) calculates own fleet from your recharges instead). Electric
  road legs and the cleaning surcharge are not in it yet, so it can differ from the sum of the legs' `co2e`.

The ids are the packages' Dcycle ids: the `package_id` of the legs in
[List Logistics Requests](https://code.dcycle.io/api-reference/logistics/list-requests.md), or the `id` in
[List Packages](https://code.dcycle.io/api-reference/logistics/list-packages.md).

## Request

### Headers

**x-api-key** `string` *required*

Your API key (see [Authentication](https://code.dcycle.io/api-reference/introduction.md#authentication)).

**Example:** `${DCYCLE_API_KEY}`

**x-organization-id** `string` *required*

Your organization UUID. Only this organization's packages are read.

**Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`

### Query Parameters

**id** `uuid` *required*

A package id, repeated: `?id=…&id=…`, 1 to 100 per request.

## Response

`200 OK` with `items` (the packages found) and `not_found` (the ids with no package in your organization).

**items** `array`

**package**

**id** `uuid`

The package's Dcycle id.

**package\_key** `string`

The package's key within your organization, as sent with its legs.

**shipment\_id** `string`

The shipment the package belongs to.

**client\_billing\_id** `string | null`

Billing client of the package, if sent.

**weight\_kg** `number | null`

Package weight in kg, if sent.

**total\_distance\_km** `number | null`

Sum of the distance of its active legs, in km; `null` until its legs are first calculated.

**total\_co2e** `number | null`

kg CO₂e of its active legs; `null` until its legs are first calculated.

**status** `string`

`active`, the only value packages have today.

**created\_at** `string`

UTC, ISO 8601.

**updated\_at** `string | null`

Last change of the package or its totals (UTC, ISO 8601): compare it with the value you last read.

**not\_found** `array[uuid]`

Requested ids with no package in your organization.

## Errors

[Problem details](https://code.dcycle.io/api-reference/errors.md). The API key and the organization are checked as in
[Create Logistics Requests (v2)](https://code.dcycle.io/api-reference/logistics/create-requests-v2.md): `401`, `400 ORGANIZATION_ID_REQUIRED`
and `403 LOGGED_USER_NOT_MEMBER`, each in [Errors](https://code.dcycle.io/api-reference/errors.md#codes). Then
`422 REQUEST_VALIDATION_FAILED` when there is no `id`, more than 100, or one that is not a UUID.

## Related Endpoints

* [Create Logistics Requests (v2)](https://code.dcycle.io/api-reference/logistics/create-requests-v2.md)
* [List Packages](https://code.dcycle.io/api-reference/logistics/list-packages.md)
* [Get Package by ID](https://code.dcycle.io/api-reference/logistics/get-package.md)


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