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

> Retrieve all employees with filtering and pagination support

# List Employees

Retrieve a paginated list of employees in your organization with support for filtering and searching.

## 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="search" type="string">
  Search employees by name or email (partial match)

  **Example:** `"john"`
</ParamField>

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

  **Available values:** `active`, `inactive`, `terminated`

  **Example:** `situation=active`
</ParamField>

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

  **Available values:** `uploaded`, `loading`

  **Example:** `status=uploaded`
</ParamField>

<ParamField query="transport_type" type="array[string]">
  Filter by transport type used in commuting periods

  **Available values:** `car`, `bus`, `train`, `metro`, `tram`, `motorbike`, `bicycle`, `walking`, `telecommuting`, `electric_kick_scooter`, `trolleybus`

  **Example:** `transport_type=car&transport_type=bus`
</ParamField>

<ParamField query="response_medium" type="array[string]">
  Filter by how commuting data was collected

  **Available values:** `manual`, `qr`, `form`, `file_upload`

  **Example:** `response_medium=form`
</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 employee objects

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

    <ResponseField name="name" type="string | null">
      Employee's full name
    </ResponseField>

    <ResponseField name="email" type="string | null">
      Employee's email address
    </ResponseField>

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

    <ResponseField name="situation" type="string | null">
      Employment status: `active`, `inactive`, or `terminated`
    </ResponseField>

    <ResponseField name="status" type="string">
      Data status: `uploaded` or `loading`
    </ResponseField>

    <ResponseField name="periods" type="array[object] | null">
      List of commuting periods with CO2e calculations

      <Expandable title="Commuting Period Object">
        <ResponseField name="id" type="string">UUID</ResponseField>
        <ResponseField name="employee_id" type="string">Parent employee UUID</ResponseField>
        <ResponseField name="start_date" type="date">Period start date</ResponseField>
        <ResponseField name="end_date" type="date | null">Period end date</ResponseField>

        <ResponseField name="transport_type" type="string | null">
          Mode of transport: `car`, `bus`, `train`, `metro`, `tram`, `motorbike`, `bicycle`, `walking`, `telecommuting`, `electric_kick_scooter`, `trolleybus`
        </ResponseField>

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

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

        <ResponseField name="renewable_energy" type="string | null">Renewable energy: `yes`, `no`, `do_not_know`</ResponseField>
        <ResponseField name="carpool" type="boolean">Whether the employee carpools</ResponseField>
        <ResponseField name="total_km" type="number | null">One-way commute distance in km</ResponseField>
        <ResponseField name="weekly_travels" type="array[integer] | null">Days of the week the employee commutes (0=Monday, 4=Friday)</ResponseField>
        <ResponseField name="weekly_telecommuting" type="array[integer] | null">Days of the week the employee telecommutes</ResponseField>
        <ResponseField name="daily_trips" type="integer">Number of one-way trips per commuting day</ResponseField>
        <ResponseField name="hours_worked_per_day" type="integer | null">Hours worked per day</ResponseField>
        <ResponseField name="total_commuting_days" type="integer | null">Total commuting days in the period</ResponseField>
        <ResponseField name="total_telecommuting_days" type="integer | null">Total telecommuting days in the period</ResponseField>
        <ResponseField name="situation" type="string | null">Period-level situation: `active`, `inactive`, `terminated`</ResponseField>
        <ResponseField name="commuting_type" type="string">Commuting classification: `in_itinere` (home→office) or `in_labore` (work-related travel)</ResponseField>
        <ResponseField name="response_medium" type="string | null">How data was collected: `manual`, `qr`, `form`, `file_upload`</ResponseField>
        <ResponseField name="origin" type="string | null">Origin address</ResponseField>
        <ResponseField name="destination" type="string | null">Destination address</ResponseField>
        <ResponseField name="co2e" type="number | null">Calculated CO2e emissions in kg</ResponseField>
        <ResponseField name="file_id" type="string | null">Source file UUID</ResponseField>
        <ResponseField name="file_name" type="string | null">Source file name</ResponseField>
        <ResponseField name="created_at" type="datetime">Record creation timestamp</ResponseField>
        <ResponseField name="updated_at" type="datetime | null">Last update timestamp</ResponseField>
      </Expandable>
    </ResponseField>

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

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

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

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

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

## Example

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

  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,
      "situation": ["active"]
  }

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

  result = response.json()
  for employee in result["items"]:
      print(f"{employee['name'] or employee['email']}")
      for period in employee.get("periods", []):
          print(f"  - {period['transport_type']}: {period['co2e']} kg CO2e")
  ```

  ```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 = {
    page: 1,
    size: 50,
    situation: ['active']
  };

  axios.get(
    'https://api.dcycle.io/v1/employees',
    { headers, params }
  )
  .then(response => {
    response.data.items.forEach(employee => {
      console.log(`${employee.name || employee.email}`);
      (employee.periods || []).forEach(period => {
        console.log(`  - ${period.transport_type}: ${period.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",
      "name": "John Smith",
      "email": "john.smith@company.com",
      "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
      "situation": "active",
      "status": "uploaded",
      "periods": [
        {
          "id": "660e8400-e29b-41d4-a716-446655440000",
          "employee_id": "550e8400-e29b-41d4-a716-446655440000",
          "start_date": "2024-01-01",
          "end_date": "2024-12-31",
          "transport_type": "car",
          "vehicle_size": "medium",
          "fuel_type": "petrol",
          "renewable_energy": "no",
          "carpool": false,
          "total_km": 15,
          "weekly_travels": [0, 1, 2, 3, 4],
          "weekly_telecommuting": null,
          "daily_trips": 1,
          "situation": "active",
          "commuting_type": "in_itinere",
          "response_medium": "form",
          "origin": "Calle Gran Vía 1, Madrid",
          "destination": "Paseo de la Castellana 100, Madrid",
          "co2e": 1245.5,
          "file_id": null,
          "file_name": null,
          "created_at": "2024-01-15T10:30:00Z",
          "updated_at": "2024-01-15T10:30:00Z"
        }
      ],
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Alice Johnson",
      "email": "alice.johnson@company.com",
      "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
      "situation": "active",
      "status": "uploaded",
      "periods": [
        {
          "id": "660e8400-e29b-41d4-a716-446655440001",
          "employee_id": "550e8400-e29b-41d4-a716-446655440001",
          "start_date": "2024-01-01",
          "end_date": "2024-12-31",
          "transport_type": "train",
          "vehicle_size": null,
          "fuel_type": "electric",
          "renewable_energy": "yes",
          "carpool": false,
          "total_km": 25,
          "weekly_travels": [1, 2, 3],
          "weekly_telecommuting": null,
          "daily_trips": 1,
          "situation": "active",
          "commuting_type": "in_itinere",
          "response_medium": "manual",
          "origin": null,
          "destination": null,
          "co2e": 456.2,
          "file_id": null,
          "file_name": null,
          "created_at": "2024-01-15T11:00:00Z",
          "updated_at": "2024-01-15T11:00:00Z"
        }
      ],
      "created_at": "2024-01-15T11:00:00Z",
      "updated_at": "2024-01-15T11:00:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "size": 50,
}
```

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

**Solution:** Verify your API key is valid and active. Get a new one from [Settings -> API](https://app.dcycle.io/settings/api).

### 404 Not Found

**Cause:** Organization not found

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

**Solution:** Verify that the `x-organization-id` header contains a valid organization UUID.

### 422 Validation Error

**Cause:** Invalid query parameters

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": [
    {
      "loc": ["query", "size"],
      "msg": "ensure this value is less than or equal to 100",
      "type": "value_error.number.not_le"
    }
  ]
}
```

**Solution:** Check that page size is between 1 and 100, and that filter values are valid enums.

## Use Cases

### Get All Active Employees

Retrieve only employees currently working:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def get_active_employees():
    """Get all active employees in the organization"""
    response = requests.get(
        "https://api.dcycle.io/v1/employees",
        headers=headers,
        params={"situation": ["active"], "size": 100}
    )
    return response.json()["items"]

active_employees = get_active_employees()
print(f"Active employees: {len(active_employees)}")
```

### Calculate Total Category 7 Emissions

Sum up all employee commuting emissions:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def get_category_7_total():
    """Calculate total Scope 3 Category 7 emissions"""
    total_co2e = 0
    page = 1

    while True:
        response = requests.get(
            "https://api.dcycle.io/v1/employees",
            headers=headers,
            params={"page": page, "size": 100, "situation": ["active"]}
        )
        data = response.json()

        for employee in data["items"]:
            for period in employee.get("periods", []):
                total_co2e += period.get("co2e", 0)

        if len(data["items"]) < 100:
            break
        page += 1

    return total_co2e

total = get_category_7_total()
print(f"Scope 3 Category 7: {total:,.0f} kg CO2e ({total/1000:.1f} tonnes)")
```

### Search Employees by Name

Find employees matching a search term:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def search_employees(search_term):
    """Search employees by name or email"""
    response = requests.get(
        "https://api.dcycle.io/v1/employees",
        headers=headers,
        params={"search": search_term, "size": 100}
    )
    return response.json()["items"]

# Find all employees with "john" in name or email
employees = search_employees("john")
for emp in employees:
    print(f"{emp['name']} - {emp['email']}")
```

### Filter by Transport Mode

Find employees using specific transport:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def get_employees_by_transport(transport_types):
    """Get employees using specific transport modes"""
    response = requests.get(
        "https://api.dcycle.io/v1/employees",
        headers=headers,
        params={"transport_type": transport_types, "size": 100}
    )
    return response.json()["items"]

# Get employees who drive or take the bus
commuters = get_employees_by_transport(["car", "bus"])
print(f"Car/bus commuters: {len(commuters)}")
```

## Pagination Guide

Navigate through large employee lists efficiently:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
def iterate_all_employees(batch_size=50):
    """Iterate through all employees in organization"""
    page = 1
    while True:
        response = requests.get(
            "https://api.dcycle.io/v1/employees",
            headers=headers,
            params={"page": page, "size": batch_size}
        )
        data = response.json()

        for employee in data["items"]:
            yield employee

        if len(data["items"]) < batch_size:
            break
        page += 1

# Process all employees
for employee in iterate_all_employees():
    print(f"Processing {employee['name'] or employee['email']}")
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Get Employee" icon="user" href="/api-reference/employees/get">
    Get a specific employee by ID
  </Card>

  <Card title="Create Employee" icon="plus" href="/api-reference/employees/create">
    Add a new employee to your organization
  </Card>

  <Card title="Update Employee" icon="pencil" href="/api-reference/employees/update">
    Modify employee details
  </Card>

  <Card title="Commuting Periods" icon="route" href="/api-reference/employees/commuting-periods/list">
    Manage commuting periods
  </Card>
</CardGroup>