> ## 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 All Vehicle Consumptions (Organization)

> Retrieve consumption records across every vehicle in your organization, in one paginated table

# List All Vehicle Consumptions (Organization)

Get a paginated list of consumption records across **every vehicle** in your organization, instead of one vehicle at a time. This powers an "all consumptions" table view — useful when a single uploaded file was split into consumptions across many vehicles and you want to review, filter, or bulk-delete them as a group.

<Note>
  **Organization-scoped**: This endpoint only returns consumptions for vehicles owned directly by the organization in `x-organization-id`. It does not include consumptions from child organizations in a holding.
</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="vehicle_id[]" type="array[string]">
  Narrow the results to specific vehicle UUIDs
</ParamField>

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

  **Available values:** `active`, `success`, `loading`, `error`
</ParamField>

<ParamField query="unit_id[]" type="array[string]">
  Filter by fuel unit UUIDs
</ParamField>

<ParamField query="file_id[]" type="array[string]">
  Filter by source file UUIDs — the primary way to isolate all consumptions created from one bulk upload, across all the vehicles it was split into
</ParamField>

<ParamField query="custom_id" type="string">
  Filter by custom identifier (substring match)
</ParamField>

<ParamField query="start_date" type="string">
  Filter consumptions with a start date on or after this date (YYYY-MM-DD)
</ParamField>

<ParamField query="end_date" type="string">
  Filter consumptions with an end date on or before this date (YYYY-MM-DD)
</ParamField>

<ParamField query="created_at_from" type="string">
  Filter consumptions created on or after this datetime (ISO 8601)
</ParamField>

<ParamField query="created_at_to" type="string">
  Filter consumptions created on or before this datetime (ISO 8601)
</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, optionally prefixed with `-` for descending

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

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

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

## Response

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

  <Expandable title="Consumption Object">
    <ResponseField name="id" type="string">
      Unique identifier (UUID) for the consumption record
    </ResponseField>

    <ResponseField name="vehicle_id" type="string">
      UUID of the vehicle this consumption belongs to
    </ResponseField>

    <ResponseField name="license_plate" type="string | null">
      License plate of the owning vehicle — the only way to identify which vehicle a row belongs to in this cross-vehicle list
    </ResponseField>

    <ResponseField name="custom_id" type="string | null">
      Custom identifier for the record, if set
    </ResponseField>

    <ResponseField name="quantity" type="float">
      Fuel/energy quantity consumed
    </ResponseField>

    <ResponseField name="unit" type="object">
      The unit of measurement (`id`, `name`, `type`)
    </ResponseField>

    <ResponseField name="start_date" type="date">
      Start date of the consumption period
    </ResponseField>

    <ResponseField name="end_date" type="date">
      End date of the consumption period
    </ResponseField>

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

    <ResponseField name="file_id" type="string | null">
      UUID of the file this consumption was bulk-uploaded from, if any
    </ResponseField>

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

    <ResponseField name="co2e" type="float | null">
      Total calculated CO2e emissions
    </ResponseField>

    <ResponseField name="total_energy_kwh" type="float | null">
      Total energy consumption in kWh for the period
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      Timestamp when the consumption record was created
    </ResponseField>

    <ResponseField name="updated_at" type="datetime | null">
      Timestamp when the record was last updated
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of matching consumption records
</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 currently applied filters. Pass this back unchanged when calling [Bulk Delete by Filters](/api-reference/vehicles/consumptions-org-bulk-delete-by-filters) with the same filters, as a safety check against stale filter state.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.dcycle.io/v2/vehicle_consumptions?file_id[]=880e8400-e29b-41d4-a716-446655440000&page=1&size=50" \
    -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
  }

  params = {
      "file_id[]": ["880e8400-e29b-41d4-a716-446655440000"],
      "page": 1,
      "size": 50
  }

  response = requests.get(
      "https://api.dcycle.io/v2/vehicle_consumptions",
      headers=headers,
      params=params
  )

  result = response.json()
  for consumption in result["items"]:
      print(f"{consumption['license_plate']}: {consumption['quantity']} ({consumption['status']})")
  ```

  ```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
  };

  const params = {
    'file_id[]': ['880e8400-e29b-41d4-a716-446655440000'],
    page: 1,
    size: 50
  };

  axios.get(
    'https://api.dcycle.io/v2/vehicle_consumptions',
    { headers, params }
  )
  .then(response => {
    response.data.items.forEach(consumption => {
      console.log(`${consumption.license_plate}: ${consumption.quantity} (${consumption.status})`);
    });
  })
  .catch(error => console.error(error));
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "vehicle_id": "550e8400-e29b-41d4-a716-446655440000",
      "license_plate": "1234-ABC",
      "custom_id": null,
      "quantity": 100.5,
      "unit": { "id": "54a709bf-79fe-4acb-ab85-5e1d7cd26eb4", "name": "litre_(l)", "type": "liquid" },
      "start_date": "2024-01-01",
      "end_date": "2024-01-31",
      "status": "success",
      "file_id": "880e8400-e29b-41d4-a716-446655440000",
      "file_name": "consumos_matriz_2024_01.csv",
      "co2e": 234.7,
      "total_energy_kwh": 987.2,
      "created_at": "2024-02-01T08:00:00Z",
      "updated_at": "2024-02-01T08:00:00Z"
    }
  ],
  "total": 100,
  "page": 1,
  "size": 50,
  "filter_hash": "b4c2d3e5f6a7b8c9"
}
```

## Common Errors

### 401 Unauthorized

**Cause:** Missing or invalid API key

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

### 422 Validation Error

**Cause:** Invalid query parameters

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": [
    {
      "loc": ["query", "status[]"],
      "msg": "value is not a valid enumeration member; permitted: 'active', 'success', 'loading', 'error'",
      "type": "type_error.enum"
    }
  ]
}
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Unique Values (Organization)" icon="chart-bar" href="/api-reference/vehicles/consumptions-org-unique-values">
    Get filter dropdown values, e.g. all source files, across the organization
  </Card>

  <Card title="Bulk Delete (Organization)" icon="trash" href="/api-reference/vehicles/consumptions-org-bulk-delete">
    Delete consumptions by ID, across any vehicle in the organization
  </Card>

  <Card title="Bulk Delete by Filters (Organization)" icon="filter" href="/api-reference/vehicles/consumptions-org-bulk-delete-by-filters">
    Delete every consumption matching the current filters, e.g. an entire uploaded file
  </Card>

  <Card title="Vehicle Consumptions" icon="list" href="/api-reference/vehicles/consumptions">
    List consumptions for a single vehicle
  </Card>
</CardGroup>