> ## Documentation Index > Fetch the complete documentation index at: https://docs.custral.com/llms.txt > Use this file to discover all available pages before exploring further. # Usage of a customer, by product > How a customer record uses each product over the last 30 days: uses per product, the change on the 30 days before, slipping, and last use. Products the customer does not use are listed too. **Requires scopes:** `usage:read` and `records:read`. The module is found from the record's object, so none is passed. `breakdown` is null when no module meters that object on this side. Counts cover every customer; named lists only include records the key can read, and a record with no usable name has `name: ""`, never its id. A record that does not exist, that the key cannot read, or that is not in `{object}` is `not_found`. ## OpenAPI ````yaml /openapi-v1.json get /v1/records/{object}/{id}/usage/by-product openapi: 3.1.0 info: title: Custral API version: v1 description: >- The curated, versioned, API-key-authenticated public REST surface (`/v1`). Every endpoint here is what the official SDKs (`@custral/sdk`) and the MCP server are built on. Authenticate with a secret API key (`sk_…`) created in **Settings → Applications**. contact: name: Custral Support email: hello@custral.com url: https://custral.com license: name: Proprietary url: https://custral.com servers: - url: https://api.custral.com description: Production security: - ApiKey: [] tags: - name: Identity description: Introspect the calling API key. - name: Records description: Create, list, retrieve, and update records on any object. - name: Objects description: Read the object (table) schema of your workspace. - name: Conversations description: View, manage, and ingest conversations and their messages. - name: MCP description: Introspect the Model Context Protocol tool surface for a key. - name: Documents description: Read record notes / page documents as markdown. paths: /v1/records/{object}/{id}/usage/by-product: get: tags: - Usage modules summary: Usage of a customer, by product description: >- How a customer record uses each product over the last 30 days: uses per product, the change on the 30 days before, slipping, and last use. Products the customer does not use are listed too. **Requires scopes:** `usage:read` and `records:read`. The module is found from the record's object, so none is passed. `breakdown` is null when no module meters that object on this side. Counts cover every customer; named lists only include records the key can read, and a record with no usable name has `name: ""`, never its id. A record that does not exist, that the key cannot read, or that is not in `{object}` is `not_found`. operationId: getRecordUsageByProduct parameters: - name: object in: path required: true description: The object, by id or key. schema: type: string example: companies - name: id in: path required: true description: The customer record id (`rec_…`). schema: type: string example: rec_123 - name: moduleId in: query required: false description: >- The usage module (`umod_…`) to read, when several meter the record's object. Defaults to the oldest. schema: type: string responses: '200': description: The customer's usage, product by product. content: application/json: schema: type: object properties: data: type: object description: The customer's usage breakdown. properties: modules: type: array items: $ref: '#/components/schemas/UsageBreakdownModule' moduleId: type: - string - 'null' description: >- The module read, or null when none meters the record's object on this side. example: umod_3Ab9xK2mQ7 breakdown: oneOf: - $ref: '#/components/schemas/CustomerUsageBreakdown' - type: 'null' reqId: $ref: '#/components/schemas/RequestId' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' components: schemas: UsageBreakdownModule: type: object description: >- A usage module metering the record's object. Pass its id as `moduleId` to read it instead. properties: id: type: string example: umod_3Ab9xK2mQ7 name: type: string example: Product usage CustomerUsageBreakdown: type: object description: >- How one customer record uses each product. Products in use are listed first and never cut; not-used products fill the rest, up to 25 rows. Only products the key can read are listed. properties: windowDays: type: integer example: 30 uses: type: number example: 900 previousUses: type: number example: 0 changePercent: type: - integer - 'null' productsUsed: type: integer example: 1 productsTotal: type: integer description: Every record in the module's product object. example: 30 weekStarts: type: array items: type: string format: date products: type: array items: $ref: '#/components/schemas/CustomerProductUsage' moreNotUsed: type: integer description: Not-used products left out past the row cap. example: 27 RequestId: type: string description: >- A per-request id (`req_…`). Quote it to support when reporting a problem. example: req_2a1f9c8e7b6d5 CustomerProductUsage: allOf: - $ref: '#/components/schemas/UsageNamedRecord' - type: object properties: uses: type: number example: 900 previousUses: type: number example: 0 changePercent: type: - integer - 'null' slippingPercent: type: - integer - 'null' description: >- The 14-day drop in whole percent when this customer is slipping on this product. lastUsedAt: type: - string - 'null' format: date-time weeks: type: array description: Uses per weekly bucket, oldest first, aligned with `weekStarts`. items: type: number Error: type: object description: >- The failure envelope. Every error carries a machine-readable `code` and the `reqId` of the failing request. properties: error: type: object properties: code: type: string example: insufficient_scope required: - code reqId: $ref: '#/components/schemas/RequestId' required: - error UsageNamedRecord: type: object description: >- A record named for display. `name` is an empty string when the record has no usable name, never its id. properties: recordId: type: string example: rec_5Bc0xJ1kP4 name: type: string example: Kestrel Logistics responses: Unauthorized: description: >- The API key is missing, unknown, inactive, or expired (`code: invalid_api_key`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_api_key reqId: req_2a1f9c8e7b6d5 Forbidden: description: >- The key lacks the scope this endpoint requires (`code: insufficient_scope`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: insufficient_scope reqId: req_2a1f9c8e7b6d5 NotFound: description: 'The object or record was not found (`code: not_found`).' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: not_found reqId: req_2a1f9c8e7b6d5 securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: sk_... description: >- A Custral **secret** API key (`sk_…`), created in Settings → Applications. Sent as `Authorization: Bearer sk_…`. The `X-Api-Key: sk_…` header is also accepted and takes precedence. Never expose a secret key in a browser. ```` ## Related topics - [Usage of a product, by customer](/api-reference/usage-modules/usage-of-a-product-by-customer.md) - [Usage by product](/blocks/embedded/usage/usage-by-product.md) - [Usage by customer](/blocks/embedded/usage/usage-by-customer.md) - [The Usage module object](/dev/api-reference/usage-modules.md) - [Usage](/data/properties/complex/usage.md)