*MCP › Reference › Rentals › Projects* # List projects > Returns the projects that group orders and work, cursor-paginated. Tenancy inherited from the parent account: a billing account also sees the projects of its parent account. TOOL `filmo_projects_list` · `projects:read` · 120/min · Server annotation: Read-only · Server annotation: Idempotent ## Arguments | Name | Type | Required | Description | | --- | --- | --- | --- | | `limit` | integer | No | Page size (1-500). Defaults to 50. = `50` | | `cursor` | string | No | Opaque cursor of the page to return. Pass the value of `pagination.nextCursor` from the previous response; treat it as opaque. | | `q` | string | No | Free-text search on the name and the external reference. | | `sort` | string | No | Sort order: up to 3 comma-separated fields, each with a leading "-" for descending (e.g. "-updatedAt,name"). Sortable fields: createdAt, updatedAt, name, projectNumber, startDate, endDate, status. Defaults to "-createdAt". Ties are broken by id, so the order is stable across pages, and a cursor is bound to the sort it was issued with. | | `status` | string | No | Filter by project status: draft, budgeted, confirmed, in_progress, invoiced, completed, cancelled or archived (legacy status present in old data). `draft`, `budgeted`, `confirmed`, `in_progress`, `invoiced`, `completed`, `cancelled`, `archived` | | `contactId` | string | No | Filter by project contact identifier. | | `projectTypeId` | string | No | Filter by project type identifier. | | `archived` | boolean | No | Filter by archived: "true" lists ONLY archived projects; "false" (or absent) excludes them from the listing. | | `includeTotal` | boolean | No | Set it to true to include `pagination.total`, the number of results that match the filters across all pages. Off by default. = `false` | | `dateFilters` | object | No | Date filters by field. A bare day (YYYY-MM-DD) is read in the business timezone; an ISO 8601 instant with offset is applied as is by gte, lte, gt and lt, while on widens it to the whole business day that contains it. Fields: created, updated. | | `dateFilters.created` | object | No | | | `dateFilters.created.gte` | string | No | From this day or instant, inclusive. | | `dateFilters.created.lte` | string | No | Up to this day or instant, inclusive. | | `dateFilters.created.gt` | string | No | Strictly after; a bare day means after the end of that day. | | `dateFilters.created.lt` | string | No | Strictly before; a bare day means before the start of that day. | | `dateFilters.created.on` | string | No | Exactly that day; an instant means the whole business day that contains it. | | `dateFilters.updated` | object | No | | | `dateFilters.updated.gte` | string | No | From this day or instant, inclusive. | | `dateFilters.updated.lte` | string | No | Up to this day or instant, inclusive. | | `dateFilters.updated.gt` | string | No | Strictly after; a bare day means after the end of that day. | | `dateFilters.updated.lt` | string | No | Strictly before; a bare day means before the start of that day. | | `dateFilters.updated.on` | string | No | Exactly that day; an instant means the whole business day that contains it. | ## Result On success the result carries `structuredContent` with `data` and `meta`. These are the attributes of `data`. | Name | Type | Description | | --- | --- | --- | | `id` | string | Unique project identifier. | | `projectNumber` | string | Human-readable project number; null if not numbered. | | `name` | string | Project name. | | `color` | string | Color associated with the project (for the UI); null if none. | | `externalReference` | string | External reference of the project (for example, from the customer system); null if not recorded. | | `projectTypeId` | string | Project type identifier; null if the project has no type. | | `projectType` | object | Compact reference to the project type; null if none. | | `projectType.id` | string | Unique project type identifier. | | `projectType.name` | string | Project type name. | | `projectType.color` | string | Color associated with the project type (for the UI); null if none. | | `contact` | object | Compact reference to the project contact; null if none. | | `contact.id` | string | Unique contact identifier. | | `contact.name` | string | Contact name. | | `location` | object | Project location; its inner fields are null when not recorded. | | `location.name` | string | Name of the place/location; null if not recorded. | | `location.address` | string | Address of the location; null if not recorded. | | `location.city` | string | City of the location; null if not recorded. | | `location.postalCode` | string | Postal code of the location; null if not recorded. | | `location.province` | string | Province or region of the location; null if not recorded. | | `location.country` | string | Country of the location; null if not recorded. | | `location.lat` | number | Latitude of the location; null if not recorded. | | `location.lng` | number | Longitude of the location; null if not recorded. | | `startDate` | string | Project start date in ISO 8601 with offset. | | `endDate` | string | Project end date in ISO 8601 with offset. | | `status` | string | Project status: draft, budgeted, confirmed, in_progress, invoiced, completed, cancelled or archived. `archived` is a LEGACY status that appears in old data; the current archived state is expressed by the `archived` boolean of this same DTO. `draft`, `budgeted`, `confirmed`, `in_progress`, `invoiced`, `completed`, `cancelled`, `archived` | | `archived` | boolean | Whether the project is archived. | | `orderIds` | string[] | Identifiers of the project orders. Order details are obtained from [`GET /api/v1/orders`](https://docs.filmo.io/rest-api/endpoint-reference/orders/list-orders)?projectId=. | | `totalOrders` | integer | Total number of orders in the project (equals orderIds.length). | | `tags` | object[] | Tags attached to the project, with their identifier and name. | | `tags.id` | string | Unique identifier of the tag. | | `tags.name` | string | Tag name. | | `customFields` | object | Custom field values by custom field identifier; the definitions are in `/api/v1/custom-fields`. | | `source` | string | Source the project was created from; null if not recorded. | | `createdAt` | string | Creation date in ISO 8601 with offset. | | `updatedAt` | string | Last update date in ISO 8601 with offset. | *Call · filmo_projects_list* ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "filmo_projects_list", "arguments": { "limit": 20 } } } ``` *Result (generated from the schema)* ```json { "structuredContent": { "data": [ { "id": "id_8f2a1c", "projectNumber": "", "name": "Example", "color": "", "externalReference": "", "projectTypeId": "proj_8f2a1c", "projectType": { "id": "id_8f2a1c", "name": "Example", "color": "" }, "contact": { "id": "id_8f2a1c", "name": "Example" }, "location": { "name": "Example", "address": "
", "city": "", "postalCode": "", "province": "", "country": "ES", "lat": 1, "lng": 1 }, "startDate": "2026-09-01T08:00:00Z", "endDate": "2026-09-01T08:00:00Z", "status": "draft", "archived": true, "orderIds": [ "orde_8f2a1c" ], "totalOrders": 1, "tags": [ { "id": "id_8f2a1c", "name": "Example" } ], "customFields": { "key": "" }, "source": "", "createdAt": "2026-09-01T08:00:00Z", "updatedAt": "2026-09-01T08:00:00Z" } ], "pagination": { "nextCursor": "eyJvIjo1MH0", "hasMore": true, "total": 1 }, "meta": { "rateLimit": { "limit": 120, "remaining": 119, "reset": 42 } } } } ``` ## Sample prompts *Prompt* ```text List the active projects and the number of orders in each. ``` ## The same operation by REST This tool runs [`GET /api/v1/projects`](https://docs.filmo.io/rest-api/endpoint-reference/projects/list-projects). --- Canonical URL: https://docs.filmo.io/mcp/tools/projects/filmo-projects-list Last updated: 2026-10-25