> ## Documentation Index > Fetch the complete documentation index at: https://docs.salesbricks.com/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve brick usage > Returns detailed usage metrics for a specific brick within a subscription, including pre-commitment amounts, used quantities, and remaining units. The remaining value can be negative if usage exceeds the pre-commitment amount. If no pre-commitment is set, `pre_commitment` and `remaining` will be 0. For pool bricks (usage aggregators), `overages` and `overage_rate` will always be 0/null; overage information appears on the individual bricks that contribute to the pool. By default, returns all historical periods. Use query parameters to filter results. ## OpenAPI ````yaml https://api.salesbricks.com/api/v2/openapi.yaml get /subscriptions/{subscription_id}/bricks/{brick_id}/usage openapi: 3.0.3 info: title: Salesbricks REST API version: 2.0.0 description: API reference for external integrations servers: - url: https://api.salesbricks.com/api/v2 description: Production - url: https://api.staging.salesbricks.com/api/v2 description: Staging security: - ApiKeyAuth: [] tags: - name: Subscriptions description: >- Operations related to subscription management, including creation, updates, and retrieving subscription details. Subscriptions can be upgraded to add / remove add-ons by using the POST /subscriptions/{subscription_id}/upgrade endpoint and can be recasted for replacing the current agreement using the POST /subscriptions/{subscription_id}/recast endpoint - name: Customers description: >- Operations related to customer management, including creation, updates, and managing customer person objects. - name: Invoices description: Operations related to subscription's invoicing details. - name: Plans description: >- Operations related to listing and getting plan details including bricks in the plan. - name: Payment Methods description: Operations related to subscription's payment method. paths: /subscriptions/{subscription_id}/bricks/{brick_id}/usage: get: tags: - Usage summary: Retrieve brick usage description: >- Returns detailed usage metrics for a specific brick within a subscription, including pre-commitment amounts, used quantities, and remaining units. The remaining value can be negative if usage exceeds the pre-commitment amount. If no pre-commitment is set, `pre_commitment` and `remaining` will be 0. For pool bricks (usage aggregators), `overages` and `overage_rate` will always be 0/null; overage information appears on the individual bricks that contribute to the pool. By default, returns all historical periods. Use query parameters to filter results. operationId: retrieveBrickUsage parameters: - in: path name: brick_id schema: type: string pattern: ^([a-zA-Z\d\-]+)$ required: true - in: query name: currentPeriod schema: type: string enum: - '1' - 'True' - 'true' description: Set to '1' or 'true' to only return usage for the current period. - in: query name: from schema: type: string description: >- Filter periods starting on or after this date. Accepts ISO 8601 format (e.g., '2024-01-01' or '2024-01-01T00:00:00'). Date-only values are interpreted in the system timezone. - in: path name: subscription_id schema: type: string pattern: ^([a-zA-Z\d\-]+)$ required: true - in: query name: to schema: type: string description: >- Filter periods ending before this date. To include periods ending on a specific date, specify the following day. Accepts ISO 8601 format (e.g., '2024-12-31' or '2024-12-31T23:59:59'). Date-only values are interpreted in the system timezone. Example: to=2025-05-01 includes periods through April 30. responses: '200': content: application/json: schema: $ref: '#/components/schemas/BrickUtilization' description: '' '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: '' '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: NotFoundResponse: value: error: code: ERR_NOT_FOUND message: >- Not found — the resource you are looking for does not exist. summary: Not Found Response description: '' components: schemas: BrickUtilization: type: object description: Brick utilization serializer for utilization API. properties: starts_at: type: string format: date-time description: The period's start date and time ends_at: type: string format: date-time description: The period's end date and time subscription_id: type: string format: uuid description: The unique identifier of the subscription brick_id: type: string format: uuid description: The unique identifier of the brick within the subscription brick_name: type: string description: The display name of the brick pre_commitment: type: integer description: >- The pre-committed amount of units for this brick. Will be 0 if no pre-commitment is set. used: type: number format: double maximum: 100000000000000 minimum: -100000000000000 exclusiveMaximum: true exclusiveMinimum: true description: >- The number of units that have been used so far. Returns an integer for whole number quantities or a decimal for fractional usage (e.g. 99.5). overages: type: number format: double maximum: 100000000000000 minimum: -100000000000000 exclusiveMaximum: true exclusiveMinimum: true description: >- The number of units that exceeded the pre-commitment. Returns an integer for whole number quantities or a decimal for fractional usage. Will be 0 if usage has not exceeded pre-commitment, if no pre-commitment is set, or if this is a pool brick (overages only appear on the individual bricks, not on the pool itself). overage_rate: type: string format: decimal pattern: ^-?\d{0,10}(?:\.\d{0,10})?$ nullable: true description: >- The cost per overage unit. Multiply overages * overage_rate to get total overage cost. Will be null if no overages, no overage pricing configured, or if this is a pool brick (overage rates only appear on the individual bricks, not on the pool itself). remaining: type: number format: double maximum: 100000000000000 minimum: -100000000000000 exclusiveMaximum: true exclusiveMinimum: true description: >- The number of units remaining in the pre-commitment. Returns an integer for whole number quantities or a decimal for fractional usage. Can be negative if usage exceeds pre-commitment. unit: type: string description: >- The unit of measurement for this brick (e.g., 'API calls', 'GB', etc.). Defaults to 'units' if not specified. pre_commitment_schedule: enum: - ALL_UPFRONT - MONTHLY - QUARTERLY - SEMI_ANNUALLY - ANNUALLY - null type: string x-spec-enum-id: 3291f1569df314cc nullable: true description: |- The pre-commitment schedule for this brick. * `ALL_UPFRONT` - All upfront * `MONTHLY` - Monthly * `QUARTERLY` - Quarterly * `SEMI_ANNUALLY` - Semi-annually * `ANNUALLY` - Annually required: - brick_id - brick_name - ends_at - overages - pre_commitment - remaining - starts_at - subscription_id - unit - used ErrorResponse: type: object description: >- Standardizes API error responses with a consistent structure containing error code and message. properties: error: $ref: '#/components/schemas/Error' required: - error Error: type: object description: >- Represents individual error details with a standardized code and descriptive message. properties: code: enum: - ERR_NOT_FOUND - ERR_BAD_REQUEST - ERR_SERVER_ERROR type: string x-spec-enum-id: dc5a5d6feae1b697 description: >- Error code indicating the type of error: NOT_FOUND for missing resources, BAD_REQUEST for invalid input, SERVER_ERROR for internal server issues * `ERR_NOT_FOUND` - ERR_NOT_FOUND * `ERR_BAD_REQUEST` - ERR_BAD_REQUEST * `ERR_SERVER_ERROR` - ERR_SERVER_ERROR message: type: string error_id: type: string format: uuid description: >- Correlation handle for SERVER_ERROR responses — quote this when contacting support; it joins to the structured server log line for the failure. Not present on 4xx responses. required: - code - message securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-SALESBRICKS-KEY description: API key for authentication ```` ## Related topics - [Usage Alerts](/products/usage-alerts.md) - [Creating a Brick](/quickstart-guide/products-plans-bricks/creating-a-brick.md) - [Submit a usage entry](/api-reference/usage/post.md)