Skip to main content

Create Custom Report

POST 
/api/v2/custom-reports

Create a new saved custom report.

Required scope: reports:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Required fields:

  • name (string, max 255): Report name
  • domain (string, max 50): Domain category (e.g., sales, inventory)
  • base_entity (string, max 100): Primary entity for the report
  • definition (object): Full report definition containing columns, filters, sorts, etc.

Optional fields:

  • description (string, max 1000): Report description
  • visibility (string): "private" (default) or "shared"
  • definition.version (integer): Schema version number
  • definition.domain (string): Domain within the definition
  • definition.filters (object): Filter tree with conjunction and children
  • definition.sorts (array): Sort rules
  • definition.limit (integer, 1-5000): Default row limit

Column requirements:

  • id (string, required): Unique column identifier (e.g., "entity.field")
  • kind (string, required): "dimension" or "measure"
  • entity (string, required): Entity the column belongs to
  • field (string, required): Field name on the entity
  • label (string, optional): Display label
  • granularity (string, optional): Time granularity for date dimensions (e.g., day, month, year)
  • aggregation (string, optional): Aggregation function for measures (e.g., sum, count, avg)

Returns 201 with the created custom report object.

Request​

Responses​

Successful response