Filmo Docs
Español

Projects

List projects

Returns the projects that group orders and work, cursor-paginated.

GET
/api/v1/projects

Request examples

curl https://app.filmo.io/api/v1/projects \
  --header "Authorization: Bearer $FILMO_API_KEY"
{
  "data": [
    {
      "id": "project_9f3a2b",
      "projectNumber": "2026-0001",
      "name": "Example project",
      "color": "Example color",
      "externalReference": "2026-0001",
      "projectTypeId": "project_type_9f3a2b",
      "projectType": {
        "id": "project_type_9f3a2b",
        "name": "Example project type",
        "color": "Example color"
      },
      "contact": {
        "id": "contact_9f3a2b",
        "name": "Example contact"
      },
      "location": {
        "name": "Example location",
        "address": "Example address",
        "city": "Madrid",
        "postalCode": "28001",
        "province": "Madrid",
        "country": "ES",
        "lat": 1,
        "lng": 1
      },
      "startDate": "2026-09-01T08:00:00.000Z",
      "endDate": "2026-09-01T08:00:00.000Z",
      "status": "draft",
      "archived": true,
      "orderIds": [
        "order_9f3a2b"
      ],
      "totalOrders": 1,
      "tags": [
        {
          "id": "tag_9f3a2b",
          "name": "Example tag"
        }
      ],
      "customFields": {
        "example": "example"
      },
      "source": "Example source",
      "createdAt": "2026-09-01T08:00:00.000Z",
      "updatedAt": "2026-09-01T08:00:00.000Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJvIjoyMH0",
    "hasMore": true,
    "total": 1
  }
}

Generated from the schema

Tenancy inherited from the parent account: a billing account also sees the projects of its parent account.

Authorizations

Bearer API key with the scope below. projects:read

Query parameters

limitintegerdefault:50

Page size (1-500). Defaults to 50.

Limits: min 1, max 500

cursorstring

Opaque cursor of the page to return. Pass the value of pagination.nextCursor from the previous response; treat it as opaque.

Limits: max length 200

createdOnstring

The creation date of the resource falls on this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset.

Limits: pattern ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

createdAfterstring

The creation date of the resource is after this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset.

Limits: pattern ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

createdBeforestring

The creation date of the resource is before this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset.

Limits: pattern ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

createdFromstring

The creation date of the resource is on or after this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset.

Limits: pattern ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

createdTostring

The creation date of the resource is on or before this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset.

Limits: pattern ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

updatedOnstring

The last update date of the resource falls on this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset.

Limits: pattern ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

updatedAfterstring

The last update date of the resource is after this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset.

Limits: pattern ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

updatedBeforestring

The last update date of the resource is before this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset.

Limits: pattern ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

updatedFromstring

The last update date of the resource is on or after this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset.

Limits: pattern ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

updatedTostring

The last update date of the resource is on or before this date. A bare day (YYYY-MM-DD, read in the business timezone) or an ISO 8601 instant with offset.

Limits: pattern ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

qstring

Free-text search on the name and the external reference.

Limits: min length 1, max length 200

sortstring

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.

Limits: max length 200

statusstring

Filter by project status: draft, budgeted, confirmed, in_progress, invoiced, completed, cancelled or archived (legacy status present in old data).

Available options: draft, budgeted, confirmed, in_progress, invoiced, completed, cancelled, archived

contactIdstring

Filter by project contact identifier.

Limits: min length 1, max length 100

projectTypeIdstring

Filter by project type identifier.

Limits: min length 1, max length 100

archivedboolean

Filter by archived: "true" lists ONLY archived projects; "false" (or absent) excludes them from the listing.

includeTotalbooleandefault:false

Set it to true to include pagination.total, the number of results that match the filters across all pages. Off by default.

Response

application/json

Successful response.

Response schema: ProjectDto

Envelope: ProjectList. meta.warnings is present only when the operation is deprecated.

Headers: X-Request-Id · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset

dataobject[]

Show child attributes
data.idstring

Unique project identifier.

data.projectNumberstring | null

Human-readable project number; null if not numbered.

data.namestring

Project name.

data.colorstring | null

Color associated with the project (for the UI); null if none.

data.externalReferencestring | null

External reference of the project (for example, from the customer system); null if not recorded.

data.projectTypeIdstring | null

Project type identifier; null if the project has no type.

data.projectTypeobject | null

Compact reference to the project type; null if none.

Show child attributes
data.projectType.idstring

Unique project type identifier.

data.projectType.namestring

Project type name.

data.projectType.colorstring | null

Color associated with the project type (for the UI); null if none.

data.contactobject | null

Compact reference to the project contact; null if none.

Show child attributes
data.contact.idstring

Unique contact identifier.

data.contact.namestring

Contact name.

data.locationobject

Project location; its inner fields are null when not recorded.

Show child attributes
data.location.namestring | null

Name of the place/location; null if not recorded.

data.location.addressstring | null

Address of the location; null if not recorded.

data.location.citystring | null

City of the location; null if not recorded.

data.location.postalCodestring | null

Postal code of the location; null if not recorded.

data.location.provincestring | null

Province or region of the location; null if not recorded.

data.location.countrystring | null

Country of the location; null if not recorded.

data.location.latnumber | null

Latitude of the location; null if not recorded.

data.location.lngnumber | null

Longitude of the location; null if not recorded.

data.startDatestring<date-time>

Project start date in ISO 8601 with offset.

data.endDatestring<date-time>

Project end date in ISO 8601 with offset.

data.statusstring

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.

Available options: draft, budgeted, confirmed, in_progress, invoiced, completed, cancelled, archived

data.archivedboolean

Whether the project is archived.

data.orderIdsstring[]

Identifiers of the project orders. Order details are obtained from GET /api/v1/orders?projectId=.

data.totalOrdersinteger

Total number of orders in the project (equals orderIds.length).

data.tagsobject[]

Tags attached to the project, with their identifier and name.

Show child attributes
data.tags.idstring

Unique identifier of the tag.

data.tags.namestring

Tag name.

data.customFieldsobject<string, any>

Custom field values by custom field identifier; the definitions are in /api/v1/custom-fields.

data.sourcestring | null

Source the project was created from; null if not recorded.

data.createdAtstring<date-time>

Creation date in ISO 8601 with offset.

data.updatedAtstring<date-time>

Last update date in ISO 8601 with offset.

paginationobject

Opaque-cursor pagination metadata.

Show child attributes
pagination.nextCursorstring | null

Opaque cursor of the next page; null when there are no more results. Pass it as cursor in the next request.

pagination.hasMoreboolean

Whether more results exist beyond this page.

pagination.totalinteger

Number of results matching the filters across all pages. Present only when the request sets includeTotal=true.

Limits: min 0

metaobject

Additional information about the response.

Show child attributes
meta.warningsobject[]

Lifecycle warnings; present only when the operation is deprecated.

Show child attributes
meta.warnings.codestring

Stable warning code.

Available options: deprecated

meta.warnings.messagestring

For people: what is deprecated, until when, and what to use.

meta.warnings.sunsetstring

Day (YYYY-MM-DD) the operation stops being served.

meta.warnings.replacementstring | null

operationId of the operation to use instead, or null if there is none.

meta.warnings.linkstring

Where the deprecation is documented (the changelog).

Errors

StatusCodesMeaning
400validation_errorMalformed query or body. errors[] lists every offending field with its stable code.

401, 403, 429, 500 can be returned by any operation. Errors

Deprecation

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

Related

Related pages

Link to this section: Related pages

  • Rentals

    Project

    The project, as returned by the API.

Was this page helpful?

Cookies

If you accept, we use Google cookies to measure visits and show you ads. Privacy policy

More information

With your consent we use Google Ads and Google Analytics cookies to measure which campaigns bring visitors and requests, and to show you Filmo ads on other sites. Without acceptance, Google receives cookieless measurement signals, including your IP address, browser information and a cleaned page URL. Your choice is shared with the Filmo app.