> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://catena.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://catena.ferndocs.com/_mcp/server.

# Filter & Query Data

Every Telematics API endpoint accepts a set of common query parameters that let you scope results to specific fleets, connections, or time windows. This guide explains the three main identifiers and when to use each one.

---

## Fleet Identifiers

The Catena API uses several identifiers to reference fleets and their TSP connections.

| Identifier      | Description                                                                            | Example        |
| --------------- | -------------------------------------------------------------------------------------- | -------------- |
| `fleet_id`      | Catena's internal UUID for a fleet. Assigned automatically.                            | `a1b2c3d4-...` |
| `fleet_ref`     | Your organization's external reference for a fleet. Set during onboarding.             | `FLEET-42`     |
| `connection_id` | UUID for a specific Fleet + TSP pairing. Assigned when a fleet connects to a provider. | `e5f6g7h8-...` |

### Why the distinction matters

A single fleet can connect to **multiple telematics providers** (e.g., Samsara for GPS tracking and Motive for ELD compliance). Each of these links is a separate **connection**.

```mermaid
flowchart LR
    fleet["Fleet\nfleet_ref = FLEET-42"]
    conn1["Connection A\n(Samsara)"]
    conn2["Connection B\n(Motive)"]

    fleet --- conn1
    fleet --- conn2

    style fleet fill:#ffc107,stroke:none,color:#00354d
    style conn1 fill:#00bae6,stroke:none,color:#ffffff
    style conn2 fill:#00bae6,stroke:none,color:#ffffff
```

---

## Reading Data

When you query the Telematics API with a `fleet_ref`, Catena returns data from **all providers** the fleet is connected to. You don't need to know which TSP sourced a specific record.

```bash
# Returns vehicles from ALL connected TSPs for this fleet
curl 'https://api.catenatelematics.com/v2/telematics/vehicles?fleet_refs=FLEET-42'
```

If you need data from a specific provider only, add the `connection_id` filter:

```bash
# Returns vehicles from Samsara only
curl 'https://api.catenatelematics.com/v2/telematics/vehicles?fleet_refs=FLEET-42&connection_id=<CONNECTION_A_UUID>'
```

> **Info**
>
> You can also filter by `fleet_ids` (Catena's internal UUID) instead of `fleet_refs`. Use whichever identifier your system stores.

---

## Writing Data

When you **write** data (create or update a resource), Catena needs to know **which TSP** should receive the request. Since a fleet can have multiple connections, you must provide a `connection_id` in every write request.

> **Warning**
>
> Write endpoints always require a `connection_id`. Catena cannot send the same write to all TSPs — the target provider must be explicit.

For more details on write operations, see [Writing Data to TSPs](/get-started/writing-data).

---

## How to Find the Connection ID

There are two approaches depending on your use case:

#### Creating a new resource

Query the [List Connections](/api-reference/integrations/integrations-api) endpoint and filter by `fleet_refs` to find the connection you need:

```bash
curl 'https://api.catenatelematics.com/v2/integrations/connections?fleet_refs=FLEET-42'
```

The response includes the `connection_id`, `tsp_id`, and `source_name` for each connection, so you can identify the correct TSP.

#### Updating an existing resource

Retrieve the resource first — every resource returned by the Telematics API includes a `connection_id` field that tells you which TSP ingested it. Use that same `connection_id` in your update request.

```bash
# 1. Get the vehicle to find its connection_id
curl 'https://api.catenatelematics.com/v2/telematics/vehicles/{vehicle_id}'

# Response includes: "connection_id": "e5f6g7h8-..."

# 2. Use that connection_id in the update
curl -X PATCH 'https://api.catenatelematics.com/v2/telematics/vehicles/{vehicle_id}' \
  -H 'Content-Type: application/json' \
  -d '{"connection_id": "e5f6g7h8-...", "vehicle_name": "Truck 99"}'
```

> **Tip**
>
> **Best practice:** Store the `connection_id` alongside the `fleet_ref` in your system when you first discover it. This avoids an extra API call on every write operation.