> ## Documentation Index > Fetch the complete documentation index at: https://docs.phonely.ai/llms.txt > Use this file to discover all available pages before exploring further. # List usage > The organization's usage in a time range, one line item per kind of usage. Without `group_by`, the list holds one item: the organization's total, or the agent's with `agent_id`. With `group_by=agent_id`, it holds one item per agent that used anything in the range, ordered by `agent_id` and paged; their line items add up to the total. Line items cover the kinds of usage `type` lists, and more kinds can be added. ## OpenAPI ````yaml /api-reference/v1/openapi.json get /v1/organizations/{id}/usage openapi: 3.1.0 info: description: >- Authenticate every request with an org API key: `Authorization: Bearer phk_…`. title: Phonely API version: '1' servers: - description: US url: https://api.us.phonely.ai - description: AU url: https://api.au.phonely.ai security: [] paths: /v1/organizations/{id}/usage: get: tags: - Organizations summary: List usage description: >- The organization's usage in a time range, one line item per kind of usage. Without `group_by`, the list holds one item: the organization's total, or the agent's with `agent_id`. With `group_by=agent_id`, it holds one item per agent that used anything in the range, ordered by `agent_id` and paged; their line items add up to the total. Line items cover the kinds of usage `type` lists, and more kinds can be added. operationId: list_organization_usage parameters: - description: The organization's ID. in: path name: id required: true schema: description: The organization's ID. title: Id type: string - description: Usage at or after this time (ISO 8601 with a timezone). in: query name: occurred_from required: true schema: description: Usage at or after this time (ISO 8601 with a timezone). format: date-time title: Occurred From type: string - description: >- Usage before this time (ISO 8601 with a timezone). At most 366 days after `occurred_from`. in: query name: occurred_before required: true schema: description: >- Usage before this time (ISO 8601 with a timezone). At most 366 days after `occurred_from`. format: date-time title: Occurred Before type: string - description: '`agent_id` returns one item per agent instead of the total.' in: query name: group_by required: false schema: anyOf: - $ref: '#/components/schemas/UsageGroupBy' - type: 'null' description: '`agent_id` returns one item per agent instead of the total.' title: Group By - description: Only this agent's usage. A deleted agent's usage stays readable. in: query name: agent_id required: false schema: anyOf: - minLength: 1 type: string - type: 'null' description: Only this agent's usage. A deleted agent's usage stays readable. title: Agent Id - description: Items per page, 1 to 100. in: query name: limit required: false schema: default: 50 description: Items per page, 1 to 100. maximum: 100 minimum: 1 title: Limit type: integer - description: '`next_cursor` from the previous page.' in: query name: cursor required: false schema: anyOf: - type: string - type: 'null' description: '`next_cursor` from the previous page.' title: Cursor - description: Optional. Must be the key's org. in: header name: Phonely-Organization required: false schema: anyOf: - type: string - type: 'null' description: Optional. Must be the key's org. title: Phonely-Organization responses: '200': content: application/json: schema: $ref: '#/components/schemas/UsageList' description: Successful Response headers: Phonely-Organization: description: The authorized organization for this request. schema: type: string '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- The request is invalid: a malformed body, a bad or unknown field, or an unknown query parameter. '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: The API key is missing, invalid or revoked. headers: WWW-Authenticate: description: Always `Bearer`. schema: type: string '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- The key can't do this: a read-only key writing, or `Phonely-Organization` naming another org. '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: The resource doesn't exist, or belongs to another organization. '429': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Rate limited. Retry after the number of seconds in `Retry-After`. headers: Retry-After: description: Seconds until the request can be retried. schema: type: integer '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: An unexpected error. Contact support with the request ID. '503': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- Authentication, authorization or another required service is temporarily unavailable. security: - HTTPBearer: [] components: schemas: UsageGroupBy: description: >- How to split the usage: one item per agent. Known values: `agent_id`. More can be added, so handle values you don't recognize. title: UsageGroupBy type: string x-extensible-enum: - agent_id UsageList: additionalProperties: false properties: data: description: The items on this page. items: $ref: '#/components/schemas/Usage' title: Data type: array next_cursor: anyOf: - type: string - type: 'null' description: Pass as `cursor` to get the next page. `null` on the last page. title: Next Cursor required: - data - next_cursor title: UsageList type: object ErrorResponse: additionalProperties: false description: The body of every `/v1` error. properties: error: $ref: '#/components/schemas/Error' description: What went wrong. required: - error title: ErrorResponse type: object Usage: additionalProperties: false description: >- An organization's usage over a time range: its total, or one agent's share with `group_by=agent_id`. properties: agent_id: anyOf: - type: string - type: 'null' description: The agent this usage belongs to. `null` unless grouped by agent. title: Agent Id agent_name: anyOf: - type: string - type: 'null' description: >- The agent's name. `null` unless grouped by agent, or when the agent has no name. title: Agent Name line_items: description: >- The usage, one line per kind, ordered by `type`. Empty when nothing was used. items: $ref: '#/components/schemas/UsageLineItem' title: Line Items type: array object: const: usage default: usage description: The type of this object, always `usage`. title: Object type: string period_end_at: description: 'End of the time range, exclusive: `occurred_before`.' format: date-time title: Period End At type: string period_start_at: description: 'Start of the time range, inclusive: `occurred_from`.' format: date-time title: Period Start At type: string required: - object - agent_id - agent_name - period_start_at - period_end_at - line_items title: Usage type: object Error: additionalProperties: false properties: code: description: >- What went wrong, stable and machine-readable. Known values: `validation_failed`, `invalid_cursor`, `invalid_api_key`, `invalid_user_token`, `user_unavailable`, `insufficient_access`, `organization_mismatch`, `forbidden`, `not_found`, `method_not_allowed`, `conflict`, `agent_limit_reached`, `agent_too_large`, `sms_setup_required`, `opportunity_analysis_not_set_up`, `precondition_failed`, `payload_too_large`, `unsupported_media_type`, `precondition_required`, `rate_limited`, `internal_error`, `knowledge_processing_failed`, `bad_gateway`, `service_unavailable`, `gateway_timeout`. More can be added, so handle values you don't recognize. title: Code type: string x-extensible-enum: - validation_failed - invalid_cursor - invalid_api_key - invalid_user_token - user_unavailable - insufficient_access - organization_mismatch - forbidden - not_found - method_not_allowed - conflict - agent_limit_reached - agent_too_large - sms_setup_required - opportunity_analysis_not_set_up - precondition_failed - payload_too_large - unsupported_media_type - precondition_required - rate_limited - internal_error - knowledge_processing_failed - bad_gateway - service_unavailable - gateway_timeout details: description: One entry per problem field. Empty when the error has none. items: $ref: '#/components/schemas/ErrorDetail' title: Details type: array message: description: For people. Wording can change; branch on `code`. title: Message type: string request_id: anyOf: - type: string - type: 'null' description: Also in the `X-Request-Id` header. Quote it to support. title: Request Id required: - code - message - details - request_id title: Error type: object UsageLineItem: additionalProperties: false description: One kind of usage and how much of it. properties: quantity: description: How much was used, in `unit`. title: Quantity type: number type: description: >- The kind of usage, as recorded. New kinds can appear; read their `unit`. Known values: `inbound_call_minutes`, `outbound_call_minutes`, `warm_transfer_minutes`, `warm_transfer_minutes_external`, `cold_transfer_minutes`, `cold_transfer_minutes_external`, `sms_message`, `sms_message_external`, `ask_ai`, `voicemail_hangup`. More can be added, so handle values you don't recognize. title: Type type: string x-extensible-enum: - inbound_call_minutes - outbound_call_minutes - warm_transfer_minutes - warm_transfer_minutes_external - cold_transfer_minutes - cold_transfer_minutes_external - sms_message - sms_message_external - ask_ai - voicemail_hangup unit: description: >- What `quantity` counts. Known values: `minute`, `message`, `token`, `count`. More can be added, so handle values you don't recognize. title: Unit type: string x-extensible-enum: - minute - message - token - count required: - type - quantity - unit title: UsageLineItem type: object ErrorDetail: additionalProperties: false properties: field: description: >- The field the issue is about, as sent: `agent_id`, `limit`. Empty when none. title: Field type: string issue: description: >- What is wrong with the field. Known values: `required`, `unknown_field`, `invalid_json`, `invalid_type`, `invalid_value`, `out_of_range`, `invalid_cursor`, `read_only_field`. More can be added, so handle values you don't recognize. title: Issue type: string x-extensible-enum: - required - unknown_field - invalid_json - invalid_type - invalid_value - out_of_range - invalid_cursor - read_only_field message: description: 'For people: what is wrong with this field.' title: Message type: string required: - field - issue - message title: ErrorDetail type: object securitySchemes: HTTPBearer: description: 'An org API key: `Authorization: Bearer phk_…`' scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.