--- title: "Get message metrics" method: GET path: "/messages/metrics" tags: ["Messages"] --- # Get message metrics `GET /messages/metrics` ## Request - Base URL: `https://api.axilio.ai/api/v1` - URL: `https://api.axilio.ai/api/v1/messages/metrics` - Auth: API key in header `X-Axilio-Api-Key` - TypeScript: (a function with typed inputs; its response is checked against the schema) Returns your texting over a window (the last 7 days by default, starting at most a year back): texts sent and received, how the sent ones ended up (delivered, left the phone with no delivery report, unconfirmed, failed, still queued) and the delivery rate, how long they took to send and to be delivered, why they failed, your conversations and how many of the ones you texted wrote back within a day, and each phone's share with its busiest 30 minutes, to compare with the send_limit the response carries. The points chart it by the hour or the day (granularity) in time_zone; hour buckets need a window of 7 days or less. Scope it to one phone with phone_id or one conversation with conversation_id. A text counts at the time the platform stored it when sent, and when the phone received it when received. ## Query parameters - `period_start_at` string, date-time: Start of the window (RFC 3339). Defaults to 7 days before period_end_at, and may be at most a year before now. - `period_end_at` string, date-time: End of the window (RFC 3339). Defaults to now, and a later time is read as now. - `granularity` 'hour' | 'day': Bucket size: hour or day. hour is allowed for windows of 7 days or less. - `time_zone` string: IANA time zone the buckets follow, such as America/Los_Angeles: a day starts at local midnight and an hour on the local hour. An unknown name is an error. - `phone_id` string: Only this phone's texts. A phone your organization doesn't rent is not found. - `conversation_id` string, uuid: Only this conversation's texts, and only its phone. Another organization's conversation is not found. When phone_id is also given, it is ignored: the conversation names the phone. ## Response `200` OK - PhoneMessageMetrics: Your texting over a window: volume, how the texts ended up, how long they took, why they failed, your conversations, and each phone's share. - `conversations` PhoneMessageConversationMetrics, required: The window's conversations and how many of the ones you texted wrote back. - `active` integer, required: Conversations with a text in the window, in either direction. - `by_outcome` PhoneMessageOutcomes, required: How the texts you sent ended up. The five outcomes add up to the texts sent. - `delivered` integer, required: Texts delivered (status delivered). - `failed` integer, required: Texts that failed (status failed); the failures list says why. - `no_report` integer, required: Texts that left the phone but never got a delivery report (status sent). Some carriers return none, so this is not a failure. - `queued` integer, required: Texts still on their way to the phone, or in any status that is not final yet (status queued). - `unconfirmed` integer, required: Texts the phone had but never said whether it sent (status unconfirmed). Not counted as failed. - `replied` integer, required: Of the conversations you texted, those where they wrote back within 24 hours of one of your texts in the window. The reply may land after the window ends. GET /conversations?replied=false lists the rest. - `reply_latency_ms` PhoneMessageLatency, required: A time distribution in milliseconds: the median and the 95th percentile, each interpolated between the two nearest texts. - `p50` integer, required: Median, in milliseconds. - `p95` integer, required: 95th percentile, in milliseconds. - `reply_rate` number, double, nullable, required: Replied over texted, from 0 to 1. Null when you texted no conversation. - `response_latency_ms` PhoneMessageLatency, required: A time distribution in milliseconds: the median and the 95th percentile, each interpolated between the two nearest texts. - `p50` integer, required: Median, in milliseconds. - `p95` integer, required: 95th percentile, in milliseconds. - `started` integer, required: Conversations whose first text ever, in either direction, falls in the window. - `texted` integer, required: Conversations in which you sent a text in the window. - `delivery_latency_ms` PhoneMessageLatency, required: A time distribution in milliseconds: the median and the 95th percentile, each interpolated between the two nearest texts. - `p50` integer, required: Median, in milliseconds. - `p95` integer, required: 95th percentile, in milliseconds. - `delivery_rate` number, double, nullable, required: Delivered over sent, not counting texts still queued, from 0 to 1. Null when nothing settled. - `failures` PhoneMessageFailure[], nullable, required: Why texts failed, most failures first. - `conversations` integer, required: Different conversations these texts were in: what GET /conversations?error_code= lists for the same period and scope. - `count` integer, required: Texts that failed for this reason in the window. - `error_code` 'phone_unreachable' | 'no_result' | 'policy_off' | 'expired' | 'no_subscription' | 'no_service' | 'radio_off' | 'carrier_rejected' | 'phone_rate_limited' | 'media_fetch_failed' | 'connection_lost' | 'queue_full' | 'send_failed', required: Why the texts failed: the same codes as a message's error_code. A failure reported without a code reads as send_failed. More codes may be added; treat one you don't know as a failure you don't handle. - `numbers` integer, required: Different numbers these texts were to. - `phones` PhoneMessageFailurePhone[], nullable, required: The count by phone, most first. - `count` integer, required: Texts that failed on this phone for this reason. - `phone_id` string, required: The phone the texts failed on. - `period_end_at` string, date-time, required: End of the window, as resolved: never later than now. - `period_start_at` string, date-time, required: Start of the window, as resolved. - `phones` PhoneMessagePhoneMetrics[], nullable, required: One entry per phone in scope, most texts sent first: every phone your organization rents, even one with no texts, or the one phone or conversation asked for. - `conversations` integer, required: Conversations on this phone with a text in the window. - `delivered` integer, required: Texts delivered (status delivered). - `delivery_rate` number, double, nullable, required: Delivered over sent, not counting texts still queued, from 0 to 1. Null when nothing settled. - `failed` integer, required: Texts that failed (status failed); the failures list says why. - `no_report` integer, required: Texts that left the phone but never got a delivery report (status sent). Some carriers return none, so this is not a failure. - `peak_at` string, date-time, nullable, required: Start of the busiest slot (the latest, if several tie). Null when the phone sent nothing. - `peak_sent_30m` integer, required: The most texts the phone sent in any 30-minute slot of the window, to compare with send_limit. Slots start on the hour and half hour, in UTC. - `phone_id` string, required: The phone. - `queued` integer, required: Texts still on their way to the phone, or in any status that is not final yet (status queued). - `received` integer, required: Texts the phone received in the window. - `sent` integer, required: Texts the phone sent in the window. - `unconfirmed` integer, required: Texts the phone had but never said whether it sent (status unconfirmed). Not counted as failed. - `points` PhoneMessageMetricsPoint[], nullable, required: One point per bucket (granularity, in time_zone), oldest first, every measure present. The first bucket starts at or before the window's start. - `delivered` integer, required: Texts delivered (status delivered). - `failed` integer, required: Texts that failed (status failed); the failures list says why. - `no_report` integer, required: Texts that left the phone but never got a delivery report (status sent). Some carriers return none, so this is not a failure. - `period_start_at` string, date-time, required: Start of the bucket (RFC 3339, UTC): a local hour or a local midnight in time_zone. - `queued` integer, required: Texts still on their way to the phone, or in any status that is not final yet (status queued). - `received` integer, required: Texts your phones received in the bucket. - `send_p50_ms` integer, nullable, required: Median time from storing a text to the phone sending it, in milliseconds, over the bucket's texts. Null when none was sent. - `send_p95_ms` integer, nullable, required: 95th percentile of the same time, in milliseconds. Null when none was sent. - `sent` integer, required: Texts you sent in the bucket. - `unconfirmed` integer, required: Texts the phone had but never said whether it sent (status unconfirmed). Not counted as failed. - `send_latency_ms` PhoneMessageLatency, required: A time distribution in milliseconds: the median and the 95th percentile, each interpolated between the two nearest texts. - `p50` integer, required: Median, in milliseconds. - `p95` integer, required: 95th percentile, in milliseconds. - `send_limit` PhoneMessageSendLimit, required: The most texts one phone may send in a stretch of time. - `count` integer, required: Texts one phone may send per window. - `window_seconds` integer, required: The length of the window, in seconds. - `totals` PhoneMessageMetricsTotals, required: The window's texts in all. - `delivered` integer, required: Texts delivered (status delivered). - `failed` integer, required: Texts that failed (status failed); the failures list says why. - `no_report` integer, required: Texts that left the phone but never got a delivery report (status sent). Some carriers return none, so this is not a failure. - `numbers_received_from` integer, required: Different numbers that texted you in the window. - `numbers_texted` integer, required: Different numbers you texted in the window. - `phones_sending` integer, required: Phones that sent at least one text in the window. - `queued` integer, required: Texts still on their way to the phone, or in any status that is not final yet (status queued). - `received` integer, required: Texts your phones received in the window, counted at the time the phone received them. - `sent` integer, required: Texts you sent in the window, counted at the time the platform stored them. Equals delivered + no_report + unconfirmed + failed + queued. - `unconfirmed` integer, required: Texts the phone had but never said whether it sent (status unconfirmed). Not counted as failed. ## Other responses - `404`: Not Found - `422`: Unprocessable Entity - `500`: Internal Server Error ## Changes - **2026-10-24** `ecca093572e0`: 1 info - endpoint added [Operation history](https://skmtc.dev/axilioai/apis/axilio-api-2/changes/messages/metrics/get.md) --- [API](https://skmtc.dev/axilioai/apis/axilio-api-2.md) - [All operations](https://skmtc.dev/axilioai/apis/axilio-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/axilioai/apis/axilio-api-2/revisions/62aa324803a7?raw)