> ## 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 time series > Returns usage submitted against a brick, aggregated into fixed-size buckets (hour, day, week, or month). Decoupled from billing periods: the response contains only the raw sum of units per bucket and does NOT include pre-commitment, remaining, overages, or overage rate. For commitment-scoped fields, use the /usage endpoint instead. Buckets are aligned to the subscription's time zone. Missing buckets (no events submitted) are returned with count=0 so the series is contiguous. Pool bricks: when the brick is a usage pool, counts are summed in the pool's own unit space (`pool_count`, after each contributing brick's `pool_unit_rate` conversion). For raw event counts against an individual pooled brick, query that brick directly. ## OpenAPI ````yaml https://api.salesbricks.com/api/v2/openapi.yaml get /subscriptions/{subscription_id}/bricks/{brick_id}/usage/series 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/series: get: tags: - Usage summary: Retrieve brick usage time series description: >- Returns usage submitted against a brick, aggregated into fixed-size buckets (hour, day, week, or month). Decoupled from billing periods: the response contains only the raw sum of units per bucket and does NOT include pre-commitment, remaining, overages, or overage rate. For commitment-scoped fields, use the /usage endpoint instead. Buckets are aligned to the subscription's time zone. Missing buckets (no events submitted) are returned with count=0 so the series is contiguous. Pool bricks: when the brick is a usage pool, counts are summed in the pool's own unit space (`pool_count`, after each contributing brick's `pool_unit_rate` conversion). For raw event counts against an individual pooled brick, query that brick directly. operationId: retrieveBrickUsageSeries parameters: - in: path name: brick_id schema: type: string pattern: ^([a-zA-Z\d\-]+)$ required: true - in: query name: from schema: type: string description: >- Start of the range (inclusive). ISO 8601 (YYYY-MM-DD or full datetime). Date-only values are interpreted in the subscription's time zone. Defaults to the subscription's current order start date. - in: path name: subscription_id schema: type: string pattern: ^([a-zA-Z\d\-]+)$ required: true - in: query name: to schema: type: string description: >- End of the range (exclusive). ISO 8601. Defaults to the current time. Must be after `from`. - in: query name: window schema: type: string enum: - day - hour - month - week description: Bucket size. Defaults to 'day'. responses: '200': content: application/json: schema: $ref: '#/components/schemas/BrickUsageSeries' 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: BrickUsageSeries: type: object description: >- Windowed usage time series for a brick. Decoupled from billing periods and commitment-period concepts (pre-commitment, remaining, overages). properties: subscription_id: type: string format: uuid brick_id: type: string format: uuid brick_name: type: string unit: type: string description: >- The unit of measurement for this brick (e.g., 'API calls'). Defaults to 'Unit'. window: enum: - hour - day - week - month type: string x-spec-enum-id: 39c3a720d4c2ac43 description: |- The bucket size: hour, day, week, or month. * `hour` - hour * `day` - day * `week` - week * `month` - month buckets: type: array items: $ref: '#/components/schemas/BrickUsageBucket' required: - brick_id - brick_name - buckets - subscription_id - unit - window 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 BrickUsageBucket: type: object description: One bucket in a windowed usage time series. properties: starts_at: type: string format: date-time description: The bucket's start (inclusive) ends_at: type: string format: date-time description: The bucket's end (exclusive) count: type: number format: double maximum: 100000000000000 minimum: -100000000000000 exclusiveMaximum: true exclusiveMinimum: true description: >- The total usage submitted in this bucket. Integer for whole quantities, decimal for fractional. required: - count - ends_at - starts_at 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 - [Creating a Brick](/quickstart-guide/products-plans-bricks/creating-a-brick.md) - [Submit a usage entry](/api-reference/usage/post.md) - [Usage Alerts](/products/usage-alerts.md)