> ## 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 Transport Combinations

> Retrieve all valid transport type, travel method, and attribute combinations that have an emission factor

# List Transport Combinations

Returns every valid combination of `transport_type`, `travel_method`, `refrigerated`, `electric`, and `detail` that has a mapped emission factor in Dcycle. Use this endpoint to discover which combinations are accepted before creating or importing transport routes.

<Tip>
  Always validate your transport sections against this list before submitting them. Sections with an invalid combination will be rejected with an `INVALID_TRANSPORT_COMBINATION` error.
</Tip>

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

All query parameters are optional and act as filters on the full combination list.

<ParamField query="transport_type" type="string">
  Filter by transport mode.

  Accepted values: `road`, `air`, `maritime`, `rail`, `do_not_know`

  Use `do_not_know` when the mode is unknown — Dcycle will infer it automatically from the origin/destination pair (road for same-country, road-reachable routes; air otherwise).
</ParamField>

<ParamField query="travel_method" type="string">
  Filter by the specific vehicle type within the transport mode.

  Accepted values: `car`, `truck`, `motorbike`, `bicycle`, `electric_kick_scooter`

  Not all transport types support every travel method. Call this endpoint without filters to see which `transport_type` + `travel_method` pairings are valid.
</ParamField>

<ParamField query="refrigerated" type="boolean">
  Filter to combinations that require (or do not require) refrigerated transport.
</ParamField>

<ParamField query="electric" type="boolean">
  Filter to combinations that use an electric vehicle.
</ParamField>

<ParamField query="detail" type="string">
  Filter by the detail sub-category used for distance- or weight-banded emission factors.

  Common values follow the patterns `distance:ge:<km>`, `distance:lt:<km>`, `weight:ge:<kg>`.
</ParamField>

## Response

Returns an array of `TransportCombinationSch` objects.

<ResponseField name="transport_type" type="string">
  Transport mode for this combination: `road`, `air`, `maritime`, `rail`, or `do_not_know`.
</ResponseField>

<ResponseField name="travel_method" type="string | null">
  Vehicle type within the mode (`car`, `truck`, `motorbike`, `bicycle`, `electric_kick_scooter`), or `null` when the mode does not distinguish by vehicle.
</ResponseField>

<ResponseField name="refrigerated" type="boolean">
  Whether this combination applies to refrigerated (temperature-controlled) transport.
</ResponseField>

<ResponseField name="electric" type="boolean">
  Whether this combination applies to electric vehicles.
</ResponseField>

<ResponseField name="detail" type="string | null">
  Sub-category selector used to pick the correct emission factor when distance or cargo weight affects the factor value. `null` when no sub-category is needed.

  Examples:

  * `"distance:ge:4000"` — air routes ≥ 4,000 km
  * `"distance:ge:1500"` — air routes ≥ 1,500 km and \< 4,000 km
  * `"weight:ge:32000"` — road truck routes carrying > 32,000 kg
  * `"weight:ge:3500"` — road truck routes carrying ≤ 7,500 kg
</ResponseField>

<ResponseField name="boundaries" type="array | null">
  Distance or weight bands that define the applicability of this combination. Each entry describes one boundary condition.

  <Expandable title="Boundary object">
    <ResponseField name="from" type="number | null">
      Lower bound of the band (inclusive).
    </ResponseField>

    <ResponseField name="to" type="number | null">
      Upper bound of the band (exclusive). `null` means no upper limit.
    </ResponseField>

    <ResponseField name="unit" type="string">
      Unit for the boundary values, e.g. `"km"` or `"kg"`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="reference_product" type="string | null">
  Internal name of the ecoinvent emission factor activity mapped to this combination. Useful for traceability and debugging emission factor lookups.

  **Example:** `"transport, freight, lorry >32 metric ton, EURO6 {GLO}| transport, freight, lorry >32 metric ton, EURO6 | Cut-off, U"`
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  # List all combinations
  curl "https://api.dcycle.io/v1/transports/combinations" \
    -H "x-api-key: ${DCYCLE_API_KEY}" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}"

  # Filter to road truck combinations only
  curl "https://api.dcycle.io/v1/transports/combinations?transport_type=road&travel_method=truck" \
    -H "x-api-key: ${DCYCLE_API_KEY}" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}"

  # Filter to air, non-refrigerated combinations
  curl "https://api.dcycle.io/v1/transports/combinations?transport_type=air&refrigerated=false" \
    -H "x-api-key: ${DCYCLE_API_KEY}" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}"
  ```

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

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

  # List all combinations
  response = requests.get(
      "https://api.dcycle.io/v1/transports/combinations",
      headers=headers,
  )
  combinations = response.json()
  print(f"Total combinations: {len(combinations)}")

  # Filter to road truck combinations
  response = requests.get(
      "https://api.dcycle.io/v1/transports/combinations",
      headers=headers,
      params={"transport_type": "road", "travel_method": "truck"},
  )
  truck_combinations = response.json()
  for combo in truck_combinations:
      detail = combo.get("detail") or "no detail"
      print(f"Truck | refrigerated={combo['refrigerated']} | {detail}")
  ```

  ```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 headers = {
    'x-api-key': apiKey,
    'x-organization-id': orgId,
  };

  // List all combinations
  axios.get('https://api.dcycle.io/v1/transports/combinations', { headers })
    .then(response => {
      const combinations = response.data;
      console.log(`Total combinations: ${combinations.length}`);

      // Filter to air combinations locally
      const airCombos = combinations.filter(c => c.transport_type === 'air');
      airCombos.forEach(combo => {
        console.log(`Air | refrigerated=${combo.refrigerated} | detail=${combo.detail}`);
      });
    })
    .catch(error => console.error(error));

  // Or filter server-side
  axios.get('https://api.dcycle.io/v1/transports/combinations', {
    headers,
    params: { transport_type: 'air', refrigerated: false },
  })
    .then(response => console.log(`Non-refrigerated air combos: ${response.data.length}`))
    .catch(error => console.error(error));
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
[
  {
    "transport_type": "road",
    "travel_method": "truck",
    "refrigerated": false,
    "electric": false,
    "detail": "weight:ge:32000",
    "boundaries": [
      { "from": 32000, "to": null, "unit": "kg" }
    ],
    "reference_product": "transport, freight, lorry >32 metric ton, EURO6 {GLO}| transport, freight, lorry >32 metric ton, EURO6 | Cut-off, U"
  },
  {
    "transport_type": "road",
    "travel_method": "truck",
    "refrigerated": false,
    "electric": false,
    "detail": "weight:ge:16000",
    "boundaries": [
      { "from": 16000, "to": 32000, "unit": "kg" }
    ],
    "reference_product": "transport, freight, lorry 16-32 metric ton, EURO6 {GLO}| transport, freight, lorry 16-32 metric ton, EURO6 | Cut-off, U"
  },
  {
    "transport_type": "air",
    "travel_method": null,
    "refrigerated": false,
    "electric": false,
    "detail": "distance:ge:4000",
    "boundaries": [
      { "from": 4000, "to": null, "unit": "km" }
    ],
    "reference_product": "transport, freight, aircraft, long haul {GLO}| transport, freight, aircraft, long haul | Cut-off, U"
  },
  {
    "transport_type": "maritime",
    "travel_method": null,
    "refrigerated": false,
    "electric": false,
    "detail": null,
    "boundaries": null,
    "reference_product": "transport, freight, sea, container ship {GLO}| transport, freight, sea, container ship | Cut-off, U"
  }
]
```

## How `detail` Is Selected Automatically

When you create a transport route, Dcycle selects the correct `detail` value for you based on the route's attributes:

| Transport type   | Selection logic                                                                                           |
| ---------------- | --------------------------------------------------------------------------------------------------------- |
| **Air**          | Distance bands: `distance:lt:800`, `distance:ge:800`, `distance:ge:1500`, `distance:ge:4000`              |
| **Road / Truck** | Cargo weight bands: `weight:ge:3500` (≤ 7,500 kg), `weight:ge:7500`, `weight:ge:16000`, `weight:ge:32000` |
| **Other modes**  | `detail` is always `null`                                                                                 |

You only need to specify `detail` explicitly in file uploads or direct API calls if you want to override this automatic selection.

## Common Errors

### 401 Unauthorized

**Cause:** Missing or invalid API key / Bearer token.

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

### 422 Unprocessable Entity

**Cause:** An invalid value was passed for `transport_type`, `travel_method`, or another filter parameter.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": [
    {
      "loc": ["query", "transport_type"],
      "msg": "value is not a valid enumeration member; permitted: 'road', 'air', 'maritime', 'rail', 'do_not_know'",
      "type": "type_error.enum"
    }
  ]
}
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Transport Overview" icon="truck" href="/api-reference/transport/overview">
    Learn the full Transport API data model and workflow
  </Card>

  <Card title="Get Transport Route" icon="magnifying-glass" href="/api-reference/transport/get">
    Retrieve a single transport route with its sections and emissions
  </Card>

  <Card title="Upload Transport File" icon="arrow-up-from-bracket" href="/api-reference/transport/upload">
    Bulk-create transport routes from a spreadsheet file
  </Card>

  <Card title="Presigned URL Upload" icon="cloud-arrow-up" href="/api-reference/transport/presigned-url">
    Upload large files directly to S3 via a presigned URL
  </Card>
</CardGroup>