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

> Retrieve all business travels with filtering and pagination support

# List Business Travels

Retrieve a paginated list of business travel records in your organization with support for filtering by transport type, status, and date range.

## 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="transport_type[]" type="array[string]">
  Filter by transport type

  **Available values:** `car`, `metro`, `train`, `trolleybus`, `bus`, `motorbike`, `aircraft`, `ferry`

  **Example:** `transport_type[]=train&transport_type[]=aircraft`
</ParamField>

<ParamField query="status[]" type="array[string]">
  Filter by status

  **Available values:** `active`, `pending`, `loading`, `completed`, `error`

  **Example:** `status[]=active`
</ParamField>

<ParamField query="start_date" type="date">
  Filter by minimum travel date (inclusive)

  **Format:** `YYYY-MM-DD`

  **Example:** `2024-01-01`
</ParamField>

<ParamField query="end_date" type="date">
  Filter by maximum travel date (inclusive)

  **Format:** `YYYY-MM-DD`

  **Example:** `2024-12-31`
</ParamField>

<ParamField query="name" type="string">
  Search by name (case-insensitive substring match)

  **Example:** `offsite`
</ParamField>

<ParamField query="name[]" type="array[string]">
  Filter by exact name values (multi-select, OR logic)

  **Example:** `name[]=Team offsite&name[]=Client visit`
</ParamField>

<ParamField query="file_id[]" type="array[uuid]">
  Filter by source file UUID. Pass `00000000-0000-0000-0000-000000000000` to filter for records with no associated file.

  **Example:** `file_id[]=3fa85f64-5717-4562-b3fc-2c963f66afa6`
</ParamField>

<ParamField query="created_at_from" type="datetime">
  Filter records created on or after this timestamp (inclusive)

  **Format:** `YYYY-MM-DDTHH:MM:SSZ`
</ParamField>

<ParamField query="created_at_to" type="datetime">
  Filter records created on or before this timestamp (inclusive)

  **Format:** `YYYY-MM-DDTHH:MM:SSZ`
</ParamField>

<ParamField query="co2e_status" type="string">
  Filter by CO2e calculation status

  **Available values:** `calculated`, `not_calculated`
</ParamField>

<ParamField query="sort" type="string">
  Sort field. Prefix with `-` for descending order. Can be repeated for multi-sort.

  **Available values:** `start_date`, `-start_date`, `end_date`, `-end_date`, `name`, `-name`, `created_at`, `-created_at`, `updated_at`, `-updated_at`

  **Example:** `-start_date`
</ParamField>

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

  **Example:** `2`
</ParamField>

<ParamField query="size" type="integer" default="50">
  Number of items per page (max 100)

  **Example:** `50`
</ParamField>

## Response

<ResponseField name="items" type="array[object]">
  Array of business travel objects

  <Expandable title="Business Travel Object">
    <ResponseField name="id" type="string">
      Unique identifier (UUID)
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization UUID
    </ResponseField>

    <ResponseField name="name" type="string | null">
      Travel record label
    </ResponseField>

    <ResponseField name="email" type="string | null">
      Traveler email
    </ResponseField>

    <ResponseField name="origin" type="string | null">
      Starting location address
    </ResponseField>

    <ResponseField name="destination" type="string | null">
      Ending location address
    </ResponseField>

    <ResponseField name="distance_km" type="number | null">
      Distance traveled in kilometers
    </ResponseField>

    <ResponseField name="distance_source" type="string | null">
      How the distance was obtained: `manual` (provided directly), `geodesic` (great-circle for aircraft), or `google_maps` (other transport types with origin/destination)
    </ResponseField>

    <ResponseField name="origin_geocode" type="object | null">
      Geocoded origin location details (when available)

      <Expandable title="geocode fields">
        <ResponseField name="origin_geocode.country_code" type="string">ISO country code</ResponseField>
        <ResponseField name="origin_geocode.place_id" type="string">Place identifier</ResponseField>
        <ResponseField name="origin_geocode.address_formatted" type="string">Formatted address</ResponseField>
        <ResponseField name="origin_geocode.latitude" type="number">Latitude coordinate</ResponseField>
        <ResponseField name="origin_geocode.longitude" type="number">Longitude coordinate</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="destination_geocode" type="object | null">
      Geocoded destination location details (when available). Same structure as `origin_geocode`.
    </ResponseField>

    <ResponseField name="transport_type" type="string">
      Mode of transport: `car`, `metro`, `train`, `trolleybus`, `bus`, `motorbike`, `aircraft`, `ferry`
    </ResponseField>

    <ResponseField name="travel_type" type="string">
      Trip type: `one_way` or `round`
    </ResponseField>

    <ResponseField name="travel_number" type="integer">
      Number of trips
    </ResponseField>

    <ResponseField name="passenger_number" type="integer">
      Number of passengers per trip
    </ResponseField>

    <ResponseField name="start_date" type="date">
      Travel start date
    </ResponseField>

    <ResponseField name="end_date" type="date">
      Travel end date
    </ResponseField>

    <ResponseField name="vehicle_size" type="string | null">
      Vehicle size (car only): `small`, `medium`, `large`
    </ResponseField>

    <ResponseField name="fuel_type" type="string | null">
      Fuel type (car only): `diesel`, `petrol`, `natural_gas`, `lpg`, `electric`, `hybrid`, `not_fuel_based`, `do_not_know`
    </ResponseField>

    <ResponseField name="renewable_energy" type="string | null">
      Renewable energy usage: `yes`, `no`, `do_not_know`
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status: `active`, `pending`, `loading`, `completed`, `error`
    </ResponseField>

    <ResponseField name="source" type="string">
      How the record was created: `manual`, `bulk_upload`, `form`, `api`
    </ResponseField>

    <ResponseField name="co2e" type="number | null">
      Calculated CO2 equivalent emissions in kg
    </ResponseField>

    <ResponseField name="file_id" type="string | null">
      UUID of the source bulk-upload file, if any
    </ResponseField>

    <ResponseField name="file_name" type="string | null">
      Name of the source file, if any
    </ResponseField>

    <ResponseField name="uploaded_by" type="object | null">
      The user who created this record

      <Expandable title="user fields">
        <ResponseField name="uploaded_by.id" type="string">User UUID</ResponseField>
        <ResponseField name="uploaded_by.first_name" type="string | null">First name</ResponseField>
        <ResponseField name="uploaded_by.last_name" type="string | null">Last name</ResponseField>
        <ResponseField name="uploaded_by.profile_img_url" type="string | null">Profile image URL</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Creation timestamp
    </ResponseField>

    <ResponseField name="updated_at" type="datetime | null">
      Last update timestamp
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of records matching the filter
</ResponseField>

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

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

<ResponseField name="filter_hash" type="string">
  Hash of the current filter state — use to detect if filters have changed
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.dcycle.io/v1/business-travels?page=1&size=50&status[]=active" \
    -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

  response = requests.get(
      "https://api.dcycle.io/v1/business-travels",
      headers={
          "x-api-key": os.getenv("DCYCLE_API_KEY"),
          "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
      },
      params={
          "page": 1,
          "size": 50,
          "status[]": ["active"],
          "start_date": "2024-01-01",
          "end_date": "2024-12-31",
      },
  )

  result = response.json()
  print(f"Page {result['page']}, {result['total']} total records")
  for travel in result["items"]:
      print(f"{travel['transport_type']}: {travel['origin']} -> {travel['destination']} ({travel['co2e']} kg CO2e)")
  ```

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

  axios.get(
    'https://api.dcycle.io/v1/business-travels',
    {
      headers: {
        'x-api-key': process.env.DCYCLE_API_KEY,
        'x-organization-id': process.env.DCYCLE_ORG_ID,
      },
      params: {
        page: 1,
        size: 50,
        'status[]': ['active'],
        start_date: '2024-01-01',
        end_date: '2024-12-31',
      },
    }
  )
  .then(({ data }) => {
    console.log(`Page ${data.page}, ${data.total} total records`);
    data.items.forEach(travel => {
      console.log(`${travel.transport_type}: ${travel.origin} -> ${travel.destination} (${travel.co2e} kg CO2e)`);
    });
  })
  .catch(error => console.error(error));
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
      "name": "Madrid–Barcelona train",
      "email": null,
      "origin": "Madrid, Spain",
      "destination": "Barcelona, Spain",
      "distance_km": 621.5,
      "distance_source": "google_maps",
      "origin_geocode": {
        "country_code": "ES",
        "place_id": "ChIJgTwKgJcpQg0RaSKMYcHeNsQ",
        "address_formatted": "Madrid, Spain",
        "latitude": 40.4168,
        "longitude": -3.7038
      },
      "destination_geocode": {
        "country_code": "ES",
        "place_id": "ChIJ5TCOcRaYpBIRCmZHTz37sEQ",
        "address_formatted": "Barcelona, Spain",
        "latitude": 41.3874,
        "longitude": 2.1686
      },
      "transport_type": "train",
      "travel_type": "one_way",
      "travel_number": 2,
      "passenger_number": 1,
      "start_date": "2024-12-01",
      "end_date": "2024-12-01",
      "vehicle_size": null,
      "fuel_type": null,
      "renewable_energy": null,
      "status": "active",
      "source": "manual",
      "co2e": 24.86,
      "file_id": null,
      "file_name": null,
      "uploaded_by": {
        "id": "b9f1e2d3-0000-0000-0000-000000000001",
        "first_name": "Ana",
        "last_name": "García",
        "profile_img_url": null
      },
      "created_at": "2024-12-01T10:30:00Z",
      "updated_at": "2024-12-01T10:30:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
      "name": "Client meeting London",
      "email": null,
      "origin": "Madrid, Spain",
      "destination": "London, UK",
      "distance_km": 1250.0,
      "distance_source": "geodesic",
      "origin_geocode": null,
      "destination_geocode": null,
      "transport_type": "aircraft",
      "travel_type": "round",
      "travel_number": 1,
      "passenger_number": 1,
      "start_date": "2024-11-15",
      "end_date": "2024-11-15",
      "vehicle_size": null,
      "fuel_type": null,
      "renewable_energy": null,
      "status": "active",
      "source": "manual",
      "co2e": 385.5,
      "file_id": null,
      "file_name": null,
      "uploaded_by": {
        "id": "b9f1e2d3-0000-0000-0000-000000000001",
        "first_name": "Ana",
        "last_name": "García",
        "profile_img_url": null
      },
      "created_at": "2024-11-15T08:00:00Z",
      "updated_at": "2024-11-15T08:00:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "size": 50,
  "filter_hash": "d4f9a2..."
}
```

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

### 404 Not Found

**Cause:** Organization not found

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "Organization with id=UUID('...') not found", "code": "ORGANIZATION_NOT_FOUND"}
```

## Use Cases

### Paginate Through All Records

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def get_all_business_travels(headers, **filters):
    """Paginate through all business travel records."""
    all_travels = []
    page = 1

    while True:
        response = requests.get(
            "https://api.dcycle.io/v1/business-travels",
            headers=headers,
            params={"page": page, "size": 100, **filters},
        )
        data = response.json()
        all_travels.extend(data["items"])

        if len(all_travels) >= data["total"]:
            break
        page += 1

    return all_travels
```

### Group Emissions by Transport Type

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from collections import defaultdict

travels = get_all_business_travels(
    headers,
    **{"status[]": ["active"], "start_date": "2024-01-01", "end_date": "2024-12-31"},
)

by_type = defaultdict(lambda: {"co2e": 0, "count": 0, "km": 0})
for t in travels:
    by_type[t["transport_type"]]["co2e"] += t["co2e"] or 0
    by_type[t["transport_type"]]["count"] += 1
    by_type[t["transport_type"]]["km"] += t["distance_km"] or 0

for t_type, data in sorted(by_type.items(), key=lambda x: -x[1]["co2e"]):
    print(f"{t_type}: {data['co2e']:.1f} kg CO2e, {data['km']:.0f} km ({data['count']} trips)")
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Get Business Travel" icon="magnifying-glass" href="/api-reference/business-travels/get">
    Get a specific business travel by ID
  </Card>

  <Card title="Create Business Travel" icon="plus" href="/api-reference/business-travels/create">
    Add a new business travel record
  </Card>

  <Card title="Update Business Travel" icon="pencil" href="/api-reference/business-travels/update">
    Modify business travel details
  </Card>

  <Card title="Delete Business Travel" icon="trash" href="/api-reference/business-travels/delete">
    Remove a business travel record
  </Card>
</CardGroup>