> ## 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 product, by customer > How a product record is used across customers over the last 30 days: customers using it, uses and the change on the 30 days before, 12 weekly buckets, top customers, customers slipping, and active customers who have never tried it. **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-customer 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-customer: get: tags: - Usage modules summary: Usage of a product, by customer description: >- How a product record is used across customers over the last 30 days: customers using it, uses and the change on the 30 days before, 12 weekly buckets, top customers, customers slipping, and active customers who have never tried it. **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: getRecordUsageByCustomer parameters: - name: object in: path required: true description: The object, by id or key. schema: type: string example: products - name: id in: path required: true description: The product 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 product's usage, customer by customer. content: application/json: schema: type: object properties: data: type: object description: The product'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/ProductUsageBreakdown' - 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 ProductUsageBreakdown: type: object description: >- How one product record is used, customer by customer. Counts cover every customer; named lists only include records the key can read. properties: windowDays: type: integer example: 30 customersUsing: type: integer description: Customers with a use of this product in the window. example: 12 activeCustomers: type: integer description: Customers with a use of any product in the module in the window. example: 40 uses: type: number example: 3000 previousUses: type: number description: Uses in the window before. example: 3410 changePercent: type: - integer - 'null' description: >- Whole percent against the window before; null when that window had no uses. example: -12 usesAllTime: type: number example: 612940 firstUsedAt: type: - string - 'null' format: date-time weeks: type: array description: 12 weekly buckets, oldest first. items: $ref: '#/components/schemas/UsageWeek' topCustomers: type: array description: Up to 5, most uses first. items: allOf: - $ref: '#/components/schemas/UsageNamedRecord' - type: object properties: uses: type: number example: 900 slipping: type: array description: >- Up to 5, steepest drop first. Last 14 days down at least 30% on the 14 before, with at least 10 uses and 3 events in the earlier window. items: allOf: - $ref: '#/components/schemas/UsageNamedRecord' - type: object properties: previous: type: number example: 400 recent: type: number example: 0 percent: type: integer description: 30-100. 100 means the customer stopped. example: 100 neverTried: type: object properties: count: type: integer description: Active customers who have never used this product. example: 2 examples: type: array description: Up to 3, most active first. items: $ref: '#/components/schemas/UsageNamedRecord' RequestId: type: string description: >- A per-request id (`req_…`). Quote it to support when reporting a problem. example: req_2a1f9c8e7b6d5 UsageWeek: type: object properties: start: type: string format: date description: >- The bucket's first UTC day. The last bucket is the seven days ending today. example: '2026-06-23' uses: type: number example: 80 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 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 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 customer, by product](/api-reference/usage-modules/usage-of-a-customer-by-product.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)