*REST API › Endpoint reference › Operations › Planner*

# List the services to cover

> Returns the staff and fleet services of a date window, with who covers them and which resources are needed.

It returns ROWS, not services: each service comes as one `summary` row (`rowKind: summary`, with `staffMemberId` and `vehicleId` always null) and one `detail` row per person or vehicle assigned to it, all sharing the same `orderServiceId`. Group by `orderServiceId`: a service is uncovered when it only has its `summary` row, and covered when it has `detail` rows with an assignee, so a null on the summary row does not mean "uncovered". Internal services (not tied to an order) come with `orderId` and `orderNumber` empty and a `serviceId` that starts with `is_`. The identifier used to assign is `orderServiceId`.

`GET /api/v1/planner/services` — scope `planner:read`

Scope: `planner:read` · 120/min · MCP: `filmo_planner_services_list`

## Authorizations

Bearer API key with the scope below. `planner:read`

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `startDate` | string<date-time> | Yes | Window start, in ISO 8601 with offset. |
| `endDate` | string<date-time> | Yes | Window end, in ISO 8601 with offset. |
| `serviceType` | string | No | Which services to fetch. Defaults to both. `crew`, `fleet`, `both` |
| `orderStatus` | string | No | Filter by status of the order they are attached to. `draft`, `reserved`, `all` |
| `projectId` | string | No | Limit to one project. |

## Request examples

*List the services to cover*

**cURL**

```bash
curl 'https://app.filmo.io/api/v1/planner/services?startDate=2026-09-01T08%3A00%3A00Z&endDate=2026-09-01T08%3A00%3A00Z' \
  --header "Authorization: Bearer $FILMO_API_KEY"
```

**Node.js**

```javascript
fetch('https://app.filmo.io/api/v1/planner/services?startDate=2026-09-01T08%3A00%3A00Z&endDate=2026-09-01T08%3A00%3A00Z', {
  headers: {
    Authorization: 'Bearer YOUR_FILMO_API_KEY'
  }
})
```

**Python**

```python
import requests

requests.get(
    "https://app.filmo.io/api/v1/planner/services?startDate=2026-09-01T08%3A00%3A00Z&endDate=2026-09-01T08%3A00%3A00Z",
    headers={
      "Authorization": "Bearer YOUR_FILMO_API_KEY"
    }
)
```

## Response

Response schema: `PlannerServiceDto`

| Status | Description |
| --- | --- |
| 200 | Successful response. |
| 400 | Invalid request (validation_error): malformed query or body. `errors[]` lists every offending field with its stable code. |
| 401 | Authentication failed (unauthorized, api_key_invalid, api_key_revoked, api_key_expired, api_key_owner_inactive, api_key_owner_not_admin). |
| 403 | Not allowed (insufficient_scope: the API key does not have the required scope, named in `requiredScope`; forbidden: the owner of the key lacks the permission the operation requires). `insufficient_scope` is answered before the request counts against the rate limit, so it carries no `RateLimit-*` headers; `forbidden` does. |
| 429 | Rate limit exceeded (rate_limited): retry after `Retry-After` seconds; `RateLimit-*` says which quota ran out. |
| 500 | Internal error (internal_error). |

**200**

| Name | Type | Description |
| --- | --- | --- |
| `data` | object[] |  |
| `data.orderServiceId` | string | Service line identifier. It is the one passed when assigning. |
| `data.rowKind` | string | Which row this is. A service comes as ONE `summary` row (the service itself, with `staffMemberId` and `vehicleId` always null) plus one `detail` row per person or vehicle assigned to it, all with the same `orderServiceId`. A service is covered when it has `detail` rows with an assignee, and uncovered when it only has the `summary` row. `summary`, `detail` |
| `data.orderId` | string | Order the service is attached to; an empty string on internal services, which belong to no order. |
| `data.orderNumber` | string | Human-readable number of that order; an empty string on internal services. |
| `data.orderStatus` | string | Order status. |
| `data.contactName` | string | Customer of the order; null if not recorded. |
| `data.projectId` | string | Associated project; null if not applicable. |
| `data.projectName` | string | Project name; null if not applicable. |
| `data.serviceId` | string | Catalogue service it comes from. |
| `data.serviceName` | string | Service name. |
| `data.serviceType` | string | Type: crew, fleet or general. |
| `data.staffMemberId` | string | Assigned staff member. Only `detail` rows carry it; it is null on the `summary` row even when the service is covered. |
| `data.vehicleId` | string | Assigned vehicle. Only `detail` rows carry it; it is null on the `summary` row even when the service is covered. |
| `data.startDate` | string<date-time> | Service start in ISO 8601 UTC. |
| `data.endDate` | string<date-time> | Service end in ISO 8601 UTC. |
| `data.status` | string | Service line status. |
| `data.qty` | number | How many units of the service are requested. |
| `data.taskId` | string | Linked schedule task; null if there is none. |
| `data.requirements` | object[] | Resources needed to cover it. |
| `data.requirements.requiredResourceType` | string | What is needed: personnel or vehicle. `personnel`, `vehicle` |
| `data.requirements.qty` | number | How many are needed. |
| `meta` | object | Additional information about the response. |
| `meta.warnings` | object[] | Lifecycle warnings; present only when the operation is deprecated. |
| `meta.warnings.code` | string | Stable warning code. `deprecated` |
| `meta.warnings.message` | string | For people: what is deprecated, until when, and what to use. |
| `meta.warnings.sunset` | string | Day (YYYY-MM-DD) the operation stops being served. |
| `meta.warnings.replacement` | string | `operationId` of the operation to use instead, or null if there is none. |
| `meta.warnings.link` | string | Where the deprecation is documented (the changelog). |

*Example response · 200*

```json
{
  "data": [
    {
      "orderServiceId": "order_service_9f3a2b",
      "rowKind": "summary",
      "orderId": "order_9f3a2b",
      "orderNumber": "2026-0001",
      "orderStatus": "Example order status",
      "contactName": "Example contact name",
      "projectId": "project_9f3a2b",
      "projectName": "Example project name",
      "serviceId": "service_9f3a2b",
      "serviceName": "Example service name",
      "serviceType": "Example service type",
      "staffMemberId": "staff_member_9f3a2b",
      "vehicleId": "vehicle_9f3a2b",
      "startDate": "2026-09-01T08:00:00.000Z",
      "endDate": "2026-09-01T08:00:00.000Z",
      "status": "Example status",
      "qty": 1,
      "taskId": "task_9f3a2b",
      "requirements": [
        {
          "requiredResourceType": "personnel",
          "qty": 1
        }
      ]
    }
  ]
}
```

## Errors

| Status | Codes | Meaning |
| --- | --- | --- |
| 400 | `validation_error` | Malformed query or body. `errors[]` lists every offending field with its stable code. |

## Deprecation

This operation is not deprecated. Deprecations are announced with a Deprecation header and a sunset date.

---

Canonical URL: https://docs.filmo.io/rest-api/endpoint-reference/planner/list-the-services-to-cover  
Last updated: 2026-10-25