> This page is for version Prod (default).
> For other versions, use one of these documentation indexes:
> - Prod (default): https://docs.chrt.com/prod/llms.txt
> - Staging: https://docs.chrt.com/staging/llms.txt
> - Dev: https://docs.chrt.com/dev/llms.txt

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

# List

GET https://api.chrt.com/tracking/sessions/list/v1

Lists sessions with filtering, sorting, and pagination. Use org_scope to restrict to owned, shared, or both (default). | auth: api_key | authz: min_org_role=operator | () -> (SessionListRes)

Reference: https://docs.chrt.com/api-reference/api-reference/tracking/sessions/list-v-1

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Servers

- `https://api.chrt.com` (Production, default)
- `https://api.dev.chrt.com` (Development)
- `https://api.staging.chrt.com` (Staging)
- `https://localhost:8000` (Local)

## Request

### Query parameters

- `sort_by` (enum, optional) — Field to sort by
  - Allowed values: `created_at_timestamp`, `last_seen_at_timestamp`, `termination_scheduled_for_timestamp`, `terminated_at_timestamp`
- `sort_order` (enum, optional) — Sort order (asc or desc)
  - Allowed values: `asc`, `desc`
- `page` (integer, optional, default: 1)
- `page_size` (integer, optional, default: 20)
- `search` (string, optional, nullable) — Full-text search query
- `org_scope` (enum, optional) — Filter by org ownership: owned, shared, or owned_and_shared
  - Allowed values: `owned`, `shared`, `owned_and_shared`
- `filter_session_ids` (list of string, optional, nullable) — Filter by selected session ids
- `filter_terminated` (boolean, optional, nullable) — Filter by terminated status
- `filter_public` (boolean, optional, nullable) — Filter by public visibility
- `filter_device_id` (string, optional, nullable) — Filter by device ID
- `filter_off_chrt_reference_id` (string, optional, nullable) — Filter by off-CHRT reference ID (exact match)
- `filter_flight_number` (string, optional, nullable) — Filter by flight number (exact match)
- `filter_flight_loaded_status` (string, optional, nullable) — Filter by flight loaded status (exact match)
- `filter_has_last_seen` (boolean, optional, nullable) — Filter by whether both last_seen_at_location and last_seen_at_timestamp are set
- `filter_created_at_timestamp_gte` (string, optional, nullable) — Filter by created_at_timestamp >= value
- `filter_created_at_timestamp_lte` (string, optional, nullable) — Filter by created\_at\_timestamp \<= value
- `filter_last_seen_at_timestamp_gte` (string, optional, nullable) — Filter by last_seen_at_timestamp >= value
- `filter_last_seen_at_timestamp_lte` (string, optional, nullable) — Filter by last\_seen\_at\_timestamp \<= value
- `filter_termination_scheduled_for_timestamp_gte` (string, optional, nullable) — Filter by termination_scheduled_for_timestamp >= value
- `filter_termination_scheduled_for_timestamp_lte` (string, optional, nullable) — Filter by termination\_scheduled\_for\_timestamp \<= value
- `filter_terminated_at_timestamp_gte` (string, optional, nullable) — Filter by terminated_at_timestamp >= value
- `filter_terminated_at_timestamp_lte` (string, optional, nullable) — Filter by terminated\_at\_timestamp \<= value

## Response

### 200

Successful Response

- `items` (list of Session2, required)
- `total_count` (integer, required)

## Errors

### 422 Unprocessable Entity Error

Validation Error

- `detail` (list of ValidationError, optional)

## Types

### Session2

- `_id` (string, required)
- `created_at_timestamp` (string, required)
- `device_id` (string, required)
- `device_mac_address` (string, required)
- `org_id` (string, required) — Must be a string starting with `org_`
- `schema_version` (integer, required)
- `comments` (string, optional, nullable)
- `flight_leg_ids` (list of string, optional)
- `flight_loaded_status_by_flight_leg_id` (map from string to string, optional)
- `flight_loaded_statuses` (list of string, optional)
- `flight_numbers` (list of string, optional)
- `geofences` (list of SessionGeofence1, optional)
- `last_seen_at_location` (LocationFeature, optional, nullable) — GeoJSON Feature with typed properties for locations The geometry field is strongly typed as Geometry (union of all geometry types) but remains optional to match the base Feature class specification. To ensure geometry is always present, validate it at runtime or make it required.
- `last_seen_at_location_city` (string, optional, nullable)
- `last_seen_at_location_large_city` (string, optional, nullable)
- `last_seen_at_timestamp` (string, optional, nullable)
- `off_chrt_reference_id` (string, optional, nullable)
- `off_chrt_shipper_org_data_id` (string, optional, nullable)
- `public` (boolean, optional, default: false)
- `shared_with_org_ids` (list of string, optional)
- `terminated` (boolean, optional, default: false)
- `terminated_at_timestamp` (string, optional, nullable)
- `termination_scheduled_for_timestamp` (string, optional, nullable)

### ValidationError

- `loc` (list of ValidationErrorLocItems, required)
- `msg` (string, required)
- `type` (string, required)
- `ctx` (ValidationErrorCtx, optional)
- `input` (any, optional)

### SessionGeofence1

- `display_name` (string, required)
- `geofence_id` (string, required)
- `location` (GeofencePointLocationFeature1, required)
- `radius_miles` (double, required)
- `entered` (boolean, optional, default: false)
- `entered_at_timestamp` (string, optional, nullable)

### LocationFeature

GeoJSON Feature with typed properties for locations The geometry field is strongly typed as Geometry (union of all geometry types) but remains optional to match the base Feature class specification. To ensure geometry is always present, validate it at runtime or make it required.

- `geometry` (LocationFeatureGeometry, required)
- `type` ("Feature", required)
- `bbox` (LocationFeatureBbox, optional, nullable)
- `id` (LocationFeatureId, optional, nullable)
- `properties` (LocationProperties, optional, nullable) — Properties for GeoJSON Feature objects

### ValidationErrorLocItems

- string
- integer

### ValidationErrorCtx

### GeofencePointLocationFeature1

- `geometry` (Point, required) — Point Model
- `type` ("Feature", required)
- `bbox` (GeofencePointLocationFeature1Bbox, optional, nullable)
- `id` (GeofencePointLocationFeature1Id, optional, nullable)
- `properties` (LocationProperties, optional, nullable) — Properties for GeoJSON Feature objects

### LocationFeatureGeometry

- `type`: `GeometryCollection` (GeometryCollection)
  - `geometries` (list of LocationFeatureGeometryDiscriminatorMappingGeometryCollectionGeometriesItems, required)
  - `bbox` (LocationFeatureGeometryDiscriminatorMappingGeometryCollectionBbox, optional, nullable)
- `type`: `LineString` (LineString)
  - `coordinates` (list of LocationFeatureGeometryDiscriminatorMappingLineStringCoordinatesItems, required)
  - `bbox` (LocationFeatureGeometryDiscriminatorMappingLineStringBbox, optional, nullable)
- `type`: `MultiLineString` (MultiLineString)
  - `coordinates` (list of list of MultiLineStringCoordinatesItemsItems, required)
  - `bbox` (MultiLineStringBbox, optional, nullable)
- `type`: `MultiPoint` (MultiPoint)
  - `coordinates` (list of MultiPointCoordinatesItems, required)
  - `bbox` (MultiPointBbox, optional, nullable)
- `type`: `MultiPolygon` (MultiPolygon)
  - `coordinates` (list of list of list of MultiPolygonCoordinatesItemsItemsItems, required)
  - `bbox` (MultiPolygonBbox, optional, nullable)
- `type`: `Point` (Point)
  - `coordinates` (PointCoordinates, required)
  - `bbox` (PointBbox, optional, nullable)
- `type`: `Polygon` (Polygon)
  - `coordinates` (list of list of PolygonCoordinatesItemsItems, required)
  - `bbox` (PolygonBbox, optional, nullable)

### LocationFeatureBbox

- list of string
- list of string

### LocationFeatureId

- integer
- string

### LocationProperties

Properties for GeoJSON Feature objects

- `address` (string, optional, nullable)
- `country_code` (string, optional, nullable)
- `name` (string, optional, nullable)
- `postal_code` (string, optional, nullable)

### Point

Point Model

- `coordinates` (PointCoordinates, required)
- `type` ("Point", required)
- `bbox` (PointBbox, optional, nullable)

### GeofencePointLocationFeature1Bbox

- list of any
- list of any

### GeofencePointLocationFeature1Id

- integer
- string

### LocationFeatureGeometryDiscriminatorMappingGeometryCollectionGeometriesItems

- `type`: `GeometryCollection` (GeometryCollection)
  - `geometries` (list of LocationFeatureGeometryDiscriminatorMappingGeometryCollectionGeometriesItems, required)
  - `bbox` (LocationFeatureGeometryDiscriminatorMappingGeometryCollectionBbox, optional, nullable)
- `type`: `LineString` (LineString)
  - `coordinates` (list of LocationFeatureGeometryDiscriminatorMappingLineStringCoordinatesItems, required)
  - `bbox` (LocationFeatureGeometryDiscriminatorMappingLineStringBbox, optional, nullable)
- `type`: `MultiLineString` (MultiLineString)
  - `coordinates` (list of list of MultiLineStringCoordinatesItemsItems, required)
  - `bbox` (MultiLineStringBbox, optional, nullable)
- `type`: `MultiPoint` (MultiPoint)
  - `coordinates` (list of MultiPointCoordinatesItems, required)
  - `bbox` (MultiPointBbox, optional, nullable)
- `type`: `MultiPolygon` (MultiPolygon)
  - `coordinates` (list of list of list of MultiPolygonCoordinatesItemsItemsItems, required)
  - `bbox` (MultiPolygonBbox, optional, nullable)
- `type`: `Point` (Point)
  - `coordinates` (PointCoordinates, required)
  - `bbox` (PointBbox, optional, nullable)
- `type`: `Polygon` (Polygon)
  - `coordinates` (list of list of PolygonCoordinatesItemsItems, required)
  - `bbox` (PolygonBbox, optional, nullable)

### LocationFeatureGeometryDiscriminatorMappingGeometryCollectionBbox

- list of string
- list of string

### LocationFeatureGeometryDiscriminatorMappingLineStringCoordinatesItems

- Position2D: list of string
- Position3D: list of string

### LocationFeatureGeometryDiscriminatorMappingLineStringBbox

- list of string
- list of string

### MultiLineStringCoordinatesItemsItems

- Position2D: list of string
- Position3D: list of string

### MultiLineStringBbox

- list of string
- list of string

### MultiPointCoordinatesItems

- Position2D: list of string
- Position3D: list of string

### MultiPointBbox

- list of string
- list of string

### MultiPolygonCoordinatesItemsItemsItems

- Position2D: list of string
- Position3D: list of string

### MultiPolygonBbox

- list of string
- list of string

### PointCoordinates

- Position2D: list of string
- Position3D: list of string

### PointBbox

- list of string
- list of string

### PolygonCoordinatesItemsItems

- Position2D: list of string
- Position3D: list of string

### PolygonBbox

- list of string
- list of string

## Examples

**Response**

```json
{
  "items": [
    {
      "_id": "string",
      "created_at_timestamp": "2024-01-15T09:30:00Z",
      "device_id": "string",
      "device_mac_address": "string",
      "org_id": "string",
      "schema_version": 1,
      "comments": "string",
      "flight_leg_ids": [
        "string"
      ],
      "flight_loaded_status_by_flight_leg_id": {},
      "flight_loaded_statuses": [
        "string"
      ],
      "flight_numbers": [
        "string"
      ],
      "geofences": [
        {
          "display_name": "string",
          "geofence_id": "string",
          "location": {
            "geometry": {
              "coordinates": [
                "string"
              ],
              "type": "string",
              "bbox": [
                "string"
              ]
            },
            "type": "string",
            "bbox": [
              "string"
            ],
            "id": 1,
            "properties": {
              "address": "string",
              "country_code": "string",
              "name": "string",
              "postal_code": "string"
            }
          },
          "radius_miles": 1.1,
          "entered": false,
          "entered_at_timestamp": "2024-01-15T09:30:00Z"
        }
      ],
      "last_seen_at_location": {
        "geometry": {
          "bbox": [
            "string"
          ],
          "coordinates": [
            "string"
          ],
          "type": "string"
        },
        "type": "string",
        "bbox": [
          "string"
        ],
        "id": 1,
        "properties": {
          "address": "string",
          "country_code": "string",
          "name": "string",
          "postal_code": "string"
        }
      },
      "last_seen_at_location_city": "string",
      "last_seen_at_location_large_city": "string",
      "last_seen_at_timestamp": "2024-01-15T09:30:00Z",
      "off_chrt_reference_id": "string",
      "off_chrt_shipper_org_data_id": "string",
      "public": false,
      "shared_with_org_ids": [
        "string"
      ],
      "terminated": false,
      "terminated_at_timestamp": "2024-01-15T09:30:00Z",
      "termination_scheduled_for_timestamp": "2024-01-15T09:30:00Z"
    }
  ],
  "total_count": 1
}
```

**SDK Code**

```python
import requests

url = "https://api.chrt.com/tracking/sessions/list/v1"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.chrt.com/tracking/sessions/list/v1';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.chrt.com/tracking/sessions/list/v1"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.chrt.com/tracking/sessions/list/v1")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.chrt.com/tracking/sessions/list/v1")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.chrt.com/tracking/sessions/list/v1', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.chrt.com/tracking/sessions/list/v1");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.chrt.com/tracking/sessions/list/v1")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```