Authy Reporting API
For new development, we encourage you to use the Verify API instead of the Authy API. The Verify API is an evolution of the Authy API with continued support for SMS, voice, and email one-time passcodes, an improved developer experience, and new features including:
- Twilio helper libraries in JavaScript, Java, C#, Python, Ruby, PHP, and Go.
- Access via the Twilio CLI.
- Improved visibility and insights.
- A push authentication SDK embeddable in your own application.
You are currently viewing the Authy API. New features and development will be added only to the Verify API. Check out the FAQ for more information and the migrating to Verify guide to get started.
The Authy Reporting API offers powerful query capability to get detailed information about your application usage. The API has three report type endpoints:
Events
GET https://api.authy.com/protected/{FORMAT}/reporting/events
URL
| Name | Description |
|---|---|
FORMATString |
The format to expect back from the REST API call. json or xml. |
Parameters
| Name | Description |
|---|---|
queryString (optional) |
Query to filter list of events in response. Default is everything. See query format (📇 PII) |
page Integer (optional) |
Page within paginated results to display. Default is 1. (🏢 not PII ) |
per_pageInteger (optional) |
Number of events to display per request. Default is 50. Maximum is 100. (🏢 not PII ) |
Response
Response will either be in json or xml format depending on the format provided in the URL
| Name | Description |
|---|---|
successBoolean |
Returns true if the request was successful. (🏢 not PII ) |
eventsArray |
List of event objects. Each event contains the following fields:
|
Use the -g (same as --globoff) option to switch off the "URL globbing parser" and allow cURL to process the square brackets in the query parameters.
Query Format
Queries to the Events Reporting API follow the following pattern:
:query[:attribute][:operator]=:value
Supported Attributes and Available Events
Report queries can be filtered by the following events:
- account_recovery_approved
- account_recovery_canceled
- account_recovery_started
- custom_message_not_allowed
- device_registration_completed
- multidevice_setting_changed
- one_touch_request_responded (note: one_touch refers to the Authy Push Authentication API
- phone_change_canceled
- phone_change_pin_sent
- phone_change_requested
- suspended_account
- token_invalid
- token_verified
- too_many_code_verifications
- totp_token_sent_via_call
- totp_token_sent
- unlock_method_changed
- user_account_deleted
- user_added
- user_phone_changed
The following events are specific to our legacy phone verification API. Please consider upgrading to Verify V2:
Queries can filter based on top level event details like name:
query[event][eq]=one_touch_request_responded
Queries can also filter based on nested parameters like device type:
query[objects.device.s_device_type][eq]=iphone
Multiple queries in one request are supported:
query[event][eq]=totp_token_sent&query[objects.user.s_locale][eq]=en
Supported Operators
The following operators can be used to compare and filter event attributes.
| Operator | Description |
eq |
Equal to |
lt |
Less than |
lte |
Less than or Equal to |
gt |
Greater than |
gte |
Greater than or Equal to |
lk |
Like or similar to |
Date Histogram
The following endpoint uses the querier service to return summaries over time of the queried events.
GET https://api.authy.com/protected/{FORMAT}/reporting/date_histogram
URL
| Name | Description |
|---|---|
FORMATString |
The format to expect back from the REST API call. json or xml. |
Parameters
| Name | Description |
|---|---|
report[:report_name][:attribute][:operator]String (required) |
Defines the queries to run, no reports returned if omitted.
|
intervalString (optional) |
Default is "month". Allowed values are:
|
scope[:attribute][:operator]String (optional) |
Defines a filter for the query. Multiple scopes are supported. For example scope[user.authy_id][eq]=123 will only return results for that user. See query format and supported operators. (📇 PII) |
page Integer (optional) |
Page within paginated results to display. Default is 1. (🏢 not PII ) |
per_pageInteger (optional) |
Number of events to display per request. Default is 50. Maximum is 100. (🏢 not PII ) |
Response
Response will either be in json or xml format depending on the format provided in the URL
| Name | Description |
|---|---|
successBoolean |
Returns true if the request was successful. (🏢 not PII ) |
reportsArray |
List of report objects. Each report contains the following fields
|
Terms
The following endpoint groups by field to roll-up summaries of specific attributes.
GET https://api.authy.com/protected/{FORMAT}/reporting/terms
URL
| Name | Description |
|---|---|
FORMATString |
The format to expect back from the REST API call. json or xml. |
Parameters
| Name | Description |
|---|---|
fieldString (required) |
Defines the attribute to group by. Only one field is supported per query. Queries can group by top level event details like name (event) or nested parameters like device type (objects.device.s_device_type). For a list of supported events and their fields, see Supported Attributes. (📇 PII) |
sizeInteger (optional) |
Number of terms to return. Default is 10. Maximum is 100. (🏢 not PII ) |
scope[:attribute][:operator]String (optional) |
Defines a filter for the query. Multiple scopes are supported. For example scope[user.authy_id][eq]=123 will only return results for that user. See query format and supported operators. (📇 PII ) |
Response
Response will either be in json or xml format depending on the format provided in the URL
Examples
Seeing this error?
[globbing] bad range in column
Make sure to use the -g (same as --globoff) option to switch off the "URL globbing parser" and allow cURL to process the square brackets in the query parameters.
Rate Limits
Rate limits are enforced by the Authy API. If your application hits the rate limit, an error will be returned and the app will be temporarily suspended.
| Limit | Time | Context |
| 30 | per minute | per application |
| 300 | per hour | per application |
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.
