> ## Documentation Index > Fetch the complete documentation index at: https://docs.wave.sa/llms.txt > Use this file to discover all available pages before exploring further. # Get usage > Returns the usage of one project for a period: total calls, answered calls, missed calls, call minutes, and an estimated cost in SAR. Requires the `usage:read` scope. **Counts.** `total_calls` counts every call that matches the filters. `calls_answered` counts calls that connected (a finished answered call is still an answered call). `calls_missed` counts calls nobody picked up. Failed, cancelled and timed-out calls count only in `total_calls`, so answered plus missed can be lower than the total. **Period.** `from` and `to` are inclusive and filter on the time the call was created. With neither, the period is all time and `period` shows `null`. `from` must not be later than `to`. **Queue.** `queue_id` matches calls that carry a queue id. Only callback calls carry one; web-calling and inbound calls never match. **Estimated cost.** The price of the answered minutes under your rate plan, in SAR with two decimals. It is an estimate and can differ from a later invoice. It is always `0.00` for a sandbox account. In a production account, calls made with a sandbox key are left out of the cost (they still count in the totals). If your plan has no price for a direction, that part is `0.00`. **Grouping.** Add `group_by` to also get a `groups` list with the same metrics per group. `day` and `hour` use the Saudi calendar (Asia/Riyadh, UTC+03:00): each `key` is the start of the day or hour with a `+03:00` offset, oldest first, and a day or hour with no calls is not listed. They need both `from` and `to`; the range can be at most 31 days for `hour` and 366 days for `day`. `status` groups by the raw call status and needs no range. `queue` lists the queues that have calls in the period (one group per queue id; calls without a queue are not listed) and needs no range; use it to fill a queue picker. The totals in `data` always cover the whole period. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/usage openapi: 3.1.0 info: title: Wave API version: 1.0.0 description: >- Wave API Platform — voice, numbers, and messaging for Saudi Arabia. Request schemas are GENERATED from the @wave-sa/shared Zod schemas — do not edit by hand (run `pnpm --filter @wave-sa/api generate:openapi`). servers: - url: https://api.wave.sa security: - bearerAuth: [] paths: /v1/usage: get: tags: - Usage summary: Get usage description: >- Returns the usage of one project for a period: total calls, answered calls, missed calls, call minutes, and an estimated cost in SAR. Requires the `usage:read` scope. **Counts.** `total_calls` counts every call that matches the filters. `calls_answered` counts calls that connected (a finished answered call is still an answered call). `calls_missed` counts calls nobody picked up. Failed, cancelled and timed-out calls count only in `total_calls`, so answered plus missed can be lower than the total. **Period.** `from` and `to` are inclusive and filter on the time the call was created. With neither, the period is all time and `period` shows `null`. `from` must not be later than `to`. **Queue.** `queue_id` matches calls that carry a queue id. Only callback calls carry one; web-calling and inbound calls never match. **Estimated cost.** The price of the answered minutes under your rate plan, in SAR with two decimals. It is an estimate and can differ from a later invoice. It is always `0.00` for a sandbox account. In a production account, calls made with a sandbox key are left out of the cost (they still count in the totals). If your plan has no price for a direction, that part is `0.00`. **Grouping.** Add `group_by` to also get a `groups` list with the same metrics per group. `day` and `hour` use the Saudi calendar (Asia/Riyadh, UTC+03:00): each `key` is the start of the day or hour with a `+03:00` offset, oldest first, and a day or hour with no calls is not listed. They need both `from` and `to`; the range can be at most 31 days for `hour` and 366 days for `day`. `status` groups by the raw call status and needs no range. `queue` lists the queues that have calls in the period (one group per queue id; calls without a queue are not listed) and needs no range; use it to fill a queue picker. The totals in `data` always cover the whole period. operationId: getUsage parameters: - name: from in: query required: false description: >- Start of the period (ISO 8601 date-time), inclusive. Needed with `group_by=day` or `hour`. schema: type: string format: date-time example: '2026-09-01T00:00:00.000Z' - name: to in: query required: false description: >- End of the period (ISO 8601 date-time), inclusive. Needed with `group_by=day` or `hour`. schema: type: string format: date-time example: '2026-09-30T23:59:59.999Z' - name: queue_id in: query required: false description: Only calls from this queue. Only callback calls carry a queue id. schema: type: string - name: group_by in: query required: false description: >- Also return `groups`: `day` or `hour` (Asia/Riyadh buckets), `status` (raw call status) or `queue` (the queues that have calls). schema: type: string enum: - day - hour - status - queue responses: '200': description: Usage for the period content: application/json: schema: $ref: '#/components/schemas/UsageResponse' '400': description: >- Invalid query: a bad date, `from` later than `to`, an unknown `group_by`, `group_by=day|hour` without `from` and `to`, or a range that is too long content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: The key does not have the `usage:read` scope content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: UsageResponse: type: object required: - data - period properties: data: type: object required: - total_calls - calls_answered - calls_missed - total_minutes - estimated_cost_sar - currency properties: total_calls: type: integer description: Every call that matches the filters. example: 120 calls_answered: type: integer description: Calls that connected (have an answer time). example: 84 calls_missed: type: integer description: Calls nobody picked up. example: 21 total_minutes: type: number description: Call minutes (seconds ÷ 60), two decimals. example: 312.5 estimated_cost_sar: type: number description: >- Estimated cost in SAR, two decimals. `0.00` for a sandbox account. example: 45.2 currency: type: string enum: - SAR example: SAR period: type: object description: The period the numbers cover. `null` means no bound. properties: from: type: string format: date-time nullable: true to: type: string format: date-time nullable: true groups: type: array description: Only present when `group_by` was sent. items: type: object required: - key - total_calls - calls_answered - calls_missed - total_minutes - estimated_cost_sar properties: key: type: string description: >- For `day` and `hour`: the start of the Riyadh day or hour, with a `+03:00` offset. For `status`: the raw call status. For `queue`: the queue id. example: '2026-09-01T00:00:00+03:00' total_calls: type: integer description: Every call that matches the filters. example: 120 calls_answered: type: integer description: Calls that connected (have an answer time). example: 84 calls_missed: type: integer description: Calls nobody picked up. example: 21 total_minutes: type: number description: Call minutes (seconds ÷ 60), two decimals. example: 312.5 estimated_cost_sar: type: number description: >- Estimated cost in SAR, two decimals. `0.00` for a sandbox account. example: 45.2 Error: type: object description: Wave's standard bilingual error envelope. required: - error_code - message - message_ar - request_id - docs_url properties: error_code: type: string enum: - INVALID_API_KEY - EXPIRED_API_KEY - REVOKED_API_KEY - SANDBOX_KEY_NOT_ALLOWED - INSUFFICIENT_PERMISSIONS - API_KEY_REVEAL_UNAVAILABLE - RATE_LIMIT_EXCEEDED - RECAPTCHA_FAILED - SANDBOX_EXPIRED - OTP_INVALID - OTP_EXPIRED - OTP_TOO_MANY_ATTEMPTS - OTP_RESEND_TOO_SOON - OTP_SEND_FAILED - INVALID_PHONE_NUMBER - CALLBACK_NOT_FOUND - CALLBACK_ALREADY_CANCELLED - CALLBACK_NOT_CANCELLABLE - CALL_NOT_FOUND - CALL_FAILED - INSUFFICIENT_CREDITS - CALL_NOT_CONTROLLABLE - CALL_NOT_ACTIVE - CALL_NOT_ANSWERED - AGENT_LEG_NOT_CONNECTED - CALL_CONTROL_FAILED - CALL_CONTROL_UNSUPPORTED - CALL_CONTROL_DISABLED - INVALID_PLAY_URL - TRANSFER_IN_PROGRESS - TRANSFER_TARGET_INVALID - TRANSFER_LIMIT_REACHED - CALL_VELOCITY_EXCEEDED - CONFERENCE_FULL - CALL_ALREADY_IN_CONFERENCE - CONFERENCE_NOT_FOUND - CONFERENCE_ENDED - QUEUE_CONTROL_FAILED - QUEUE_SERVICE_UNAVAILABLE - RECORDING_NOT_FOUND - RECORDING_URL_EXPIRED - RECORDING_SERVICE_UNAVAILABLE - CALLFLOW_AUDIO_SERVICE_UNAVAILABLE - CALLFLOW_VERSION_CONFLICT - VOICE_AUTH_DISABLED - VOICE_AUTH_NOT_FOUND - VOICE_AUTH_ASSURANCE_UNSUPPORTED - VOICE_AUTH_RATE_LIMITED - VOICE_AUTH_BLOCKED - VOICE_AUTH_BRAND_NOT_APPROVED - VOICE_AUTH_BRAND_NOT_FOUND - VOICE_AUTH_BRAND_INVALID_STATE - VOICE_AUTH_BRAND_DUPLICATE - VERIFY_DISABLED - VERIFY_NOT_FOUND - VERIFY_INVALID_CODE - VERIFY_MAX_ATTEMPTS - VERIFY_EXPIRED - VERIFY_RATE_LIMITED - VERIFY_SEND_FAILED - VERIFY_BLOCKED - VOICEMAIL_DISABLED - VOICEMAIL_NOT_FOUND - VOICEMAIL_RECORDING_NOT_FOUND - VOICEMAIL_SERVICE_UNAVAILABLE - VOICEMAIL_GREETING_INVALID - DLQ_REPLAY_DISABLED - DLQ_REPLAY_BROKER_UNAVAILABLE - MESSAGES_DISABLED - IVR_DISABLED - SANDBOX_INVALID_QUEUE - SANDBOX_QUEUE_UNAVAILABLE - SANDBOX_SIMULATED_SERVER_ERROR - SANDBOX_DESTINATION_NOT_ALLOWED - SANDBOX_MINUTES_EXCEEDED - WIDGET_ORIGIN_NOT_ALLOWED - PROJECT_NOT_FOUND - WEBHOOK_URL_INVALID - WEBHOOK_UNREACHABLE - WEBHOOK_LIMIT_EXCEEDED - WEBHOOK_URL_DUPLICATE - WEBHOOK_NOT_FOUND - WEBHOOK_VERIFICATION_FAILED - SIGNUP_EMAIL_TAKEN - SIGNUP_VALIDATION_FAILED - VITALPBX_PROVISIONING_FAILED - SIGNUP_FAILED - API_KEY_NOT_FOUND - API_KEY_REVEAL_FORBIDDEN - PRODUCTION_ACCESS_ALREADY_REQUESTED - PRODUCTION_TIER_REQUIRED - PRODUCTION_REQUEST_EXISTS - PRODUCTION_REQUEST_NOT_FOUND - PRODUCTION_REQUEST_INVALID_STATE - VALIDATION_ERROR - INTERNAL_ERROR - NOT_FOUND - PAYLOAD_TOO_LARGE - IDEMPOTENCY_KEY_CONFLICT - INVALID_CREDENTIALS - SESSION_REQUIRED - INVALID_ACCESS_TOKEN - EXPIRED_ACCESS_TOKEN - INVALID_REFRESH_TOKEN - EXPIRED_REFRESH_TOKEN - REFRESH_REUSE_DETECTED - REFRESH_ROTATION_RACE - SESSION_IDLE_TIMEOUT - WEB_CALLING_DISABLED - ORIGIN_NOT_ALLOWED - WEBRTC_CONCURRENCY_LIMIT - WCS_NOT_FOUND - WCS_EXPIRED - WCS_REVOKED - WCS_REUSE_DETECTED - WCS_NOT_ALLOWED_AS_BEARER - WEBRTC_PROVISIONING_FAILED - TURN_UNAVAILABLE - INVALID_IDENTITY - IDENTITY_CONFLICT - PROFILE_VALIDATION_FAILED - PASSWORD_VALIDATION_FAILED - INVALID_CURRENT_PASSWORD - PASSWORD_SSO_ONLY - SETUP_ALREADY_COMPLETE - INVALID_NATIONAL_ID - NAFATH_INITIATE_FAILED - NAFATH_NOT_VERIFIED - NAFATH_REJECTED - NAFATH_EXPIRED - NAFATH_ALREADY_REGISTERED - NAFATH_INVALID_WEBHOOK - NAFATH_ALREADY_VERIFIED - NAFATH_REQUIRED - ADMIN_UNAUTHORIZED - ADMIN_INVALID_CREDENTIALS - ADMIN_ORG_OWNER_EMAIL_TAKEN - ADMIN_USER_NOT_FOUND - INSUFFICIENT_ROLE - LAST_OWNER - INVALID_SCOPE - NUMBER_NOT_AVAILABLE - NUMBER_NOT_FOUND - NUMBER_ALREADY_ASSIGNED - NUMBER_PROVIDER_ERROR - PORTING_INVALID_STATE - PORTING_NOT_FOUND - OWN_DID_NUMBER_REQUIRED - OWN_DID_NUMBER_NOT_AUTHORIZED - OWN_DID_NUMBER_UNAVAILABLE - SPEND_CAP_EXCEEDED - RATE_PLAN_NOT_FOUND - PAYMENT_FAILED - DUPLICATE_USAGE_EVENT - INVOICE_NOT_FOUND - PAYMENT_NOT_FOUND - PAYMENT_AMOUNT_MISMATCH - INSUFFICIENT_PROJECT_BALANCE - INSUFFICIENT_POOL_BALANCE - PROJECT_NOT_FOUND_FOR_ALLOCATION - ENGINE_UNAUTHORIZED - CALLFLOW_TENANT_NOT_FOUND - CLI_NOT_OWNED - WEBHOOK_UNAUTHORIZED - CHANNEL_NOT_CONFIGURED - WEBHOOK_PAYLOAD_INVALID - RECIPIENT_OPTED_OUT - QUIET_HOURS_ACTIVE - CONSENT_LOCKED_BY_END_USER - INVITE_NOT_FOUND - INVITE_NOT_PENDING - INVITE_EXPIRED - INVITE_ROLE_INVALID - INVITE_ALREADY_MEMBER - INVITE_EMAIL_OTHER_ORG - INVITE_ACCOUNT_DETAILS_REQUIRED message: type: string description: English message. message_ar: type: string description: Arabic message. request_id: type: string docs_url: type: string format: uri securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: sk_sandbox_* | sk_live_* description: >- Your API key from the Wave dashboard. Sandbox keys start `sk_sandbox_`; production keys start `sk_live_`. Send as `Authorization: Bearer `. Some endpoints require a production key and specific scopes. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.