> ## 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.

# List Logistics Requests

> Retrieve a paginated and filterable list of logistics requests for your organization

[← Logistics API](/api-reference/logistics/overview)

Retrieve logistics requests created by your organization with pagination and filtering support.

<Note>
  **New API**: This endpoint is part of the new API architecture with improved design and maintainability.
</Note>

## 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>
  Your organization UUID

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

### Query Parameters

<ParamField query="page" type="integer" default="1">
  Page number for pagination
</ParamField>

<ParamField query="size" type="integer" default="50">
  Number of items per page
</ParamField>

<ParamField query="search" type="string">
  Search across movement ID and stretch ID
</ParamField>

<ParamField query="project_id" type="uuid">
  Filter by project UUID
</ParamField>

<ParamField query="clients[]" type="array[string]">
  Filter by client name(s)
</ParamField>

<ParamField query="trip_date_from" type="string">
  Filter by trip date `>=` value (YYYY-MM-DD)
</ParamField>

<ParamField query="trip_date_until" type="string">
  Filter by trip date `<=` value (YYYY-MM-DD)
</ParamField>

<ParamField query="vehicle_type[]" type="array[string]">
  Filter by vehicle type(s) (TOC codes)
</ParamField>

<ParamField query="trip_status" type="string">
  Filter by trip status (e.g. `active`, `deleted`)
</ParamField>

<ParamField query="uploaded_by[]" type="array[uuid]">
  Filter by uploader user UUID(s)
</ParamField>

<ParamField query="file_id[]" type="array[uuid]">
  Filter by source file UUID(s)
</ParamField>

<ParamField query="created_at_from" type="string">
  Filter by created\_at `>=` value (YYYY-MM-DD)
</ParamField>

<ParamField query="created_at_to" type="string">
  Filter by created\_at `<=` value (YYYY-MM-DD)
</ParamField>

## Response

Returns a paginated list of logistics requests with HTTP 200.

<ResponseField name="page" type="integer">
  Current page number
</ResponseField>

<ResponseField name="size" type="integer">
  Number of items per page
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of matching items
</ResponseField>

<ResponseField name="items" type="array[object]">
  List of logistics request objects

  <Expandable title="Request object">
    <ResponseField name="id" type="string">Request UUID</ResponseField>
    <ResponseField name="movement_id" type="string | null">Movement tracking identifier</ResponseField>
    <ResponseField name="client" type="string | null">Client name</ResponseField>
    <ResponseField name="shipment_date" type="string | null">Shipment date (YYYY-MM-DD)</ResponseField>
    <ResponseField name="origin" type="string | null">Origin location</ResponseField>
    <ResponseField name="destination" type="string | null">Destination location</ResponseField>
    <ResponseField name="distance_km" type="number | null">Calculated distance in kilometers</ResponseField>
    <ResponseField name="load" type="number | null">Load weight</ResponseField>
    <ResponseField name="load_unit" type="string">Load unit (e.g. `kg`, `t`)</ResponseField>
    <ResponseField name="toc" type="string | null">Transport operation category (vehicle type)</ResponseField>
    <ResponseField name="category" type="string | null">Transport category (e.g. `road`, `sea`, `air`)</ResponseField>
    <ResponseField name="status" type="string">Record status: `active` or `deleted`</ResponseField>
    <ResponseField name="kgco2e" type="number | null">Calculated emissions in kg CO2e (`null` if pending)</ResponseField>
    <ResponseField name="emission_intensity" type="number | null">Emission intensity (kgCO2e per tonne-km)</ResponseField>
    <ResponseField name="tkm" type="number | null">Tonne-kilometers</ResponseField>
    <ResponseField name="cleaning" type="boolean | null">Whether cleaning is required</ResponseField>
    <ResponseField name="movement_stretch" type="string | null">Movement stretch identifier</ResponseField>
    <ResponseField name="movement_stage" type="string | null">Movement stage</ResponseField>
    <ResponseField name="vehicle_license_plate" type="string | null">Vehicle license plate</ResponseField>
    <ResponseField name="trailer_license_plate" type="string | null">Trailer license plate</ResponseField>
    <ResponseField name="subcontractor" type="boolean | null">Whether this leg is subcontracted</ResponseField>
    <ResponseField name="hub_id" type="string | null">UUID of the associated logistic hub</ResponseField>
    <ResponseField name="created_at" type="datetime">Creation timestamp (ISO 8601)</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="filter_hash" type="string | null">
  Hash of the applied filters (for caching)
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --get "https://api.dcycle.io/v1/logistics/requests" \
    -H "x-api-key: ${DCYCLE_API_KEY}" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}" \
    --data-urlencode "page=1" \
    --data-urlencode "size=50" \
    --data-urlencode "search=MOV-2024" \
    --data-urlencode "trip_date_from=2024-01-01" \
    --data-urlencode "trip_date_until=2024-12-31" \
    --data-urlencode "clients[]=Acme Logistics"
  ```

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

  import requests

  api_key = os.getenv("DCYCLE_API_KEY")
  org_id = os.getenv("DCYCLE_ORG_ID")

  headers = {
      "x-api-key": api_key,
      "x-organization-id": org_id,
  }

  params = [
      ("page", 1),
      ("size", 50),
      ("search", "MOV-2024"),
      ("trip_date_from", "2024-01-01"),
      ("trip_date_until", "2024-12-31"),
      ("clients[]", "Acme Logistics"),
  ]

  response = requests.get(
      "https://api.dcycle.io/v1/logistics/requests",
      headers=headers,
      params=params,
  )
  response.raise_for_status()

  result = response.json()
  print(f"Total requests: {result['total']}")
  print(f"Page {result['page']} of {max(1, (result['total'] + result['size'] - 1) // result['size'])}")

  for item in result["items"]:
      emissions = item["kgco2e"] if item["kgco2e"] is not None else "pending"
      print(f"- {item['movement_id']}: {item['client']} | {item['origin']} to {item['destination']} | {emissions} kgCO2e")
  ```

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

  const apiKey = process.env.DCYCLE_API_KEY;
  const orgId = process.env.DCYCLE_ORG_ID;

  const params = new URLSearchParams({
    page: "1",
    size: "50",
    search: "MOV-2024",
    trip_date_from: "2024-01-01",
    trip_date_until: "2024-12-31"
  });
  params.append("clients[]", "Acme Logistics");

  axios.get("https://api.dcycle.io/v1/logistics/requests", {
    headers: {
      "x-api-key": apiKey,
      "x-organization-id": orgId
    },
    params
  })
  .then(response => {
    const { page, size, total, items } = response.data;
    console.log(`Page ${page} of ${Math.max(1, Math.ceil(total / size))}`);

    items.forEach(item => {
      const emissions = item.kgco2e ?? "pending";
      console.log(`- ${item.movement_id}: ${item.client} | ${item.origin} to ${item.destination} | ${emissions} kgCO2e`);
    });
  })
  .catch(error => console.error(error));
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    {
      "id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
      "movement_id": "MOV-2024-001234",
      "client": "Acme Logistics",
      "shipment_date": "2024-06-15",
      "origin": "Madrid, Spain",
      "destination": "Barcelona, Spain",
      "distance_km": 621.5,
      "load": 1000,
      "load_unit": "kg",
      "toc": "truck_diesel",
      "category": "road",
      "status": "active",
      "kgco2e": 45.2,
      "emission_intensity": 0.0452,
      "created_at": "2024-06-15T09:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "size": 50
}
```

## Use Cases

### List All Logistics Requests

Retrieve every page of logistics requests:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def get_all_logistics_requests(headers):
    """Retrieve all logistics requests with pagination."""
    all_requests = []
    page = 1

    while True:
        response = requests.get(
            "https://api.dcycle.io/v1/logistics/requests",
            headers=headers,
            params={"page": page, "size": 500},
        )
        response.raise_for_status()

        data = response.json()
        all_requests.extend(data["items"])

        if page * data["size"] >= data["total"]:
            break

        page += 1

    return all_requests
```

### Filter by Project and Date

Scope logistics requests to a project and shipment date range:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def get_project_requests(headers, project_id):
    """Retrieve logistics requests linked to a project for 2024."""
    response = requests.get(
        "https://api.dcycle.io/v1/logistics/requests",
        headers=headers,
        params={
            "page": 1,
            "size": 100,
            "project_id": project_id,
            "trip_date_from": "2024-01-01",
            "trip_date_until": "2024-12-31",
        },
    )
    response.raise_for_status()
    return response.json()
```

### Export to CSV

Export the current filtered page to a CSV file:

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


def export_logistics_to_csv(headers, filename="logistics_requests.csv"):
    """Export a page of logistics requests to CSV."""
    response = requests.get(
        "https://api.dcycle.io/v1/logistics/requests",
        headers=headers,
        params={"page": 1, "size": 500, "trip_status": "active"},
    )
    response.raise_for_status()

    data = response.json()
    fields = [
        "id",
        "movement_id",
        "client",
        "shipment_date",
        "origin",
        "destination",
        "distance_km",
        "load",
        "load_unit",
        "toc",
        "status",
        "kgco2e",
        "emission_intensity",
        "created_at",
    ]

    with open(filename, "w", newline="") as csvfile:
        writer = csv.DictWriter(csvfile, fieldnames=fields)
        writer.writeheader()

        for item in data["items"]:
            writer.writerow({field: item.get(field) for field in fields})

    return len(data["items"])
```

## Common Errors

### 401 Unauthorized

**Cause:** Missing or invalid API key

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}
```

### 403 Forbidden

**Cause:** The authenticated user is not a member of the organization

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Create Logistics Request" icon="plus" href="/api-reference/logistics/create-request">
    Calculate emissions for a new leg
  </Card>

  <Card title="List Packages" icon="box" href="/api-reference/logistics/list-packages">
    Retrieve all packages with aggregated emissions
  </Card>

  <Card title="Get Package by ID" icon="box-open" href="/api-reference/logistics/get-package">
    Get a package with all its legs
  </Card>

  <Card title="List Available Vehicle Types" icon="truck" href="/api-reference/logistics/list-tocs">
    Retrieve all available TOCs
  </Card>

  <Card title="Authentication Guide" icon="key" href="/docs/authentication">
    Learn how to get your API key
  </Card>
</CardGroup>