> ## Documentation Index > Fetch the complete documentation index at: https://docs.itellico.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get usage analytics > Aggregate conversation usage for the specified account. Supports configurable time ranges, bucket granularity, and optional groupings by agent, subaccount, or conversation type. ## OpenAPI ````yaml https://api.itellico.ai/v1/openapi.json get /v1/accounts/{account_id}/analytics/usage openapi: 3.1.0 info: title: itellicoAI API v1 version: 1.0.0 description: >- Public REST API for managing accounts, agents, telephony resources, and conversations. Authentication is via API key in the `X-API-Key` header. termsOfService: https://itellico.ai/legal/terms-and-conditions/ contact: name: itellicoAI Support email: support@itellico.ai license: name: Proprietary servers: - url: https://api.itellico.ai description: Production security: - APIKeyAuth: [] tags: - name: Accounts description: >- Identify the current account context and fetch core account metadata to bootstrap API usage. - name: Subaccounts description: >- Create and manage child accounts under a parent to model tenant hierarchies and delegated access. - name: Agents description: >- Define and configure conversational agents (model, transcriber, voice, behavior) used in calls and automations. - name: Providers description: >- Discover available AI model, transcriber, and voice catalogs for the current account when configuring agents. - name: Phone Numbers description: >- Manage BYOC phone numbers bound to your account; route inbound calls to agents and enable outbound calling. - name: SIP Trunks description: >- Manage BYOC SIP trunk connectivity (origination/termination endpoints and allowed IPs) used by phone numbers. - name: Calls description: >- Create, list, inspect, and connect voice calls across phone and web channels. - name: Conversations description: List and inspect conversation activity across web and telephony channels. - name: Analytics description: Usage analytics and reporting endpoints for conversation activity. paths: /v1/accounts/{account_id}/analytics/usage: get: tags: - Analytics summary: Get usage analytics description: >- Aggregate conversation usage for the specified account. Supports configurable time ranges, bucket granularity, and optional groupings by agent, subaccount, or conversation type. operationId: getUsageAnalytics parameters: - in: path name: account_id schema: title: Account Id type: string required: true - in: query name: start schema: anyOf: - format: date-time type: string - type: 'null' description: Start timestamp (ISO-8601). Defaults to 30 days before `end`. title: Start required: false description: Start timestamp (ISO-8601). Defaults to 30 days before `end`. - in: query name: end schema: anyOf: - format: date-time type: string - type: 'null' description: End timestamp (ISO-8601). Defaults to now. title: End required: false description: End timestamp (ISO-8601). Defaults to now. - in: query name: granularity schema: allOf: - description: |- Time bucket granularity for usage aggregation. Attributes: HOUR: Aggregate data by hour. DAY: Aggregate data by day. MONTH: Aggregate data by month. enum: - hour - day - month title: UsageGranularity type: string default: day description: Bucket granularity for aggregation. required: false description: Bucket granularity for aggregation. - in: query name: group_by schema: anyOf: - items: $ref: '#/components/schemas/UsageGroupBy' type: array - type: 'null' description: >- Dimensions to break results by (comma separated or repeated query params). title: Group By required: false description: >- Dimensions to break results by (comma separated or repeated query params). - in: query name: tz schema: anyOf: - type: string - type: 'null' description: IANA timezone name used for bucket boundaries (default UTC). title: Tz required: false description: IANA timezone name used for bucket boundaries (default UTC). - in: query name: limit schema: anyOf: - maximum: 500 minimum: 1 type: integer - type: 'null' description: Maximum number of time buckets to return (default 500). title: Limit required: false description: Maximum number of time buckets to return (default 500). responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/UsageResponseSchema' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' '422': description: Unprocessable Content content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' security: - APIKeyAuth: [] components: schemas: UsageGroupBy: description: |- Dimensions for grouping usage analytics. Attributes: AGENT: Group by individual agent. SUBACCOUNT: Group by subaccount (child team). TYPE: Group by conversation type. enum: - agent - subaccount - type title: UsageGroupBy type: string UsageResponseSchema: description: |- Complete usage analytics response payload. Attributes: meta: Metadata about the query and response. data: List of time buckets with aggregated usage values. properties: meta: $ref: '#/components/schemas/UsageMetaSchema' data: items: $ref: '#/components/schemas/UsageBucketSchema' title: Data type: array required: - meta title: UsageResponseSchema type: object ErrorSchema: description: |- Standard error response payload for all API endpoints. Follows industry best practices (similar to Stripe, RetellAI): - code: Machine-readable error identifier for programmatic handling - message: Human-readable description for display - detail: Optional additional context for debugging - errors: Optional list of field-level validation errors examples: - code: not_found detail: Agent with UUID 123e4567-e89b-12d3-a456-426614174000 does not exist message: Resource not found - code: validation_error errors: - field: body.email message: Invalid email format type: value_error - field: body.name message: Field required type: missing message: Validation failed properties: code: description: Machine-readable error code (e.g., 'not_found', 'validation_error') title: Code type: string message: description: Human-readable error message title: Message type: string detail: anyOf: - type: string - type: 'null' description: Optional detailed context for debugging title: Detail errors: anyOf: - items: $ref: '#/components/schemas/FieldErrorSchema' type: array - type: 'null' description: Field-level validation errors (for 422 responses) title: Errors required: - code - message title: ErrorSchema type: object UsageMetaSchema: description: |- Metadata describing the usage analytics response. Attributes: account_id: UUID of the account for this usage data. start: Start datetime of the query range. end: End datetime of the query range. granularity: Time bucket granularity used. group_by: Grouping dimensions requested. tz: Timezone applied to bucket boundaries. properties: account_id: format: uuid4 title: Account Id type: string start: format: date-time title: Start type: string end: format: date-time title: End type: string granularity: $ref: '#/components/schemas/UsageGranularity' group_by: description: Requested grouping dimensions. items: $ref: '#/components/schemas/UsageGroupBy' title: Group By type: array tz: default: UTC description: Timezone applied to bucket boundaries. title: Tz type: string required: - account_id - start - end - granularity title: UsageMetaSchema type: object UsageBucketSchema: description: |- Time bucket containing aggregated metric values. Attributes: ts: Bucket start timestamp in the requested timezone. values: List of metric values for this bucket. properties: ts: description: Bucket start timestamp in the requested timezone. format: date-time title: Ts type: string values: description: Metric values for this bucket. items: $ref: '#/components/schemas/UsageValueSchema' title: Values type: array required: - ts title: UsageBucketSchema type: object FieldErrorSchema: description: Schema for individual field validation errors. properties: field: description: Field path (e.g., 'body.name', 'query.page') title: Field type: string message: description: Human-readable error message title: Message type: string type: description: Error type (e.g., 'value_error', 'type_error') title: Type type: string required: - field - message - type title: FieldErrorSchema type: object UsageGranularity: description: |- Time bucket granularity for usage aggregation. Attributes: HOUR: Aggregate data by hour. DAY: Aggregate data by day. MONTH: Aggregate data by month. enum: - hour - day - month title: UsageGranularity type: string UsageValueSchema: description: |- Metric values aggregated for a single time bucket and dimension set. Attributes: seconds: Total conversation seconds for this value. conversations: Number of completed conversations. dimensions: Optional grouping dimension key/value pairs. properties: seconds: description: Total conversation seconds represented by this value. minimum: 0 title: Seconds type: integer conversations: description: Completed conversations represented by this value. minimum: 0 title: Conversations type: integer dimensions: anyOf: - additionalProperties: type: string type: object - type: 'null' description: Grouping dimension key/value pairs for this value. title: Dimensions required: - seconds - conversations title: UsageValueSchema type: object securitySchemes: APIKeyAuth: type: apiKey in: header name: X-API-Key ````