Menu

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

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, and PHP
  • Access via the Twilio CLI
  • Improved Visibility and Insights
  • Push authentication SDK embeddable in your own application

You are currently viewing the Authy API. The Authy API will continue to be maintained, but any new features and development will be on the Verify API. Check out the FAQ for more information and Verify API Reference 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:

  1. Events
  2. Date Histogram
  3. Terms

Events

GET https://api.authy.com/protected/{FORMAT}/reporting/events

URL

Name Description
FORMAT
String
The format to expect back from the REST API call. json or xml.

Parameters

Name Description
query
String (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_page
Integer (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
success
Boolean
Returns true if the request was successful. (🏢 not PII )
events
Array
List of event objects. Each event contains the following fields:
  • event: name of the event.
  • time: time of the event in ISO8601 format.
  • request_id: UUID of the request.
  • objects: additional information about the event.
See examples for more details. (📇 PII)

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.

        
        
        
        
        Example shows Push Authentication responses from iPhones

        Events Reporting API Example

        Example shows Push Authentication responses from iPhones

        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:

        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
              
              
              
              
              Example shows user_added events over time

              Date Histogram Reporting API Example

              Example shows user_added events over time

              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
              FORMAT
              String
              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. (📇 PII)
              interval
              String (optional)
              Default is "month". Allowed values are:
              • year
              • quarter
              • month
              • week
              • day
              • hour
              • minute
              Interval also supports time settings like "1.5h" (up to "w" for weeks).
              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_page
              Integer (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
              success
              Boolean
              Returns true if the request was successful. (🏢 not PII )
              reports
              Array
              List of report objects. Each report contains the following fields
              • timestamp: interval timestamp in Epoch format.
              • time: interval time in ISO8601 format.
              • count: number of times the event occurred in the interval.
              (🏢 not PII )
                    
                    
                    
                    
                    Example shows aggregated summary of events by name for 2019

                    Terms Reporting API Example

                    Example shows aggregated summary of events by name for 2019

                    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
                    FORMAT
                    String
                    The format to expect back from the REST API call. json or xml.

                    Parameters

                    Name Description
                    field
                    String (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)
                    size
                    Integer (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

                    Name Description
                    success
                    Boolean
                    Returns true if the request was successful. (🏢 not PII )
                    terms
                    Array
                    List of term objects. Each term contains the following fields
                    • key: field grouping (String)
                    • count: number of occurrences within the scope (Integer)
                    (🏢 not PII )

                    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.

                          
                          
                          
                          
                          Use gte and lte operators to filter date ranges

                          Events: Get logs from December 17, 2019

                          Use gte and lte operators to filter date ranges
                                
                                
                                
                                
                                Returns all token events for March, April, and May. Page 2 with 5 results per page.

                                Events: Authentication Details Q2 2019

                                Returns all token events for March, April, and May. Page 2 with 5 results per page.
                                      
                                      
                                      
                                      
                                      Multiple reports in one request are supported

                                      Date Histogram: Get Invalid Tokens and Valid Tokens over time

                                      Multiple reports in one request are supported
                                            
                                            
                                            
                                            
                                            Summary of verified tokens for a specific 3 month range

                                            Date Histogram: Verified Tokens with Scope

                                            Summary of verified tokens for a specific 3 month range
                                                  
                                                  
                                                  
                                                  
                                                  Summary of authentications by Authy ID for November 2019. "key" is the Authy ID.

                                                  Terms: Monthly Active Users

                                                  Summary of authentications by Authy ID for November 2019. "key" is the Authy ID.
                                                        
                                                        
                                                        
                                                        
                                                        Summary of authentications by device type for all of 2019. "key" is the device type.

                                                        Terms: Authentications by Device Type

                                                        Summary of authentications by device type for all of 2019. "key" is the device type.

                                                        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

                                                        Rate this page:

                                                        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 browsing the Twilio tag on Stack Overflow.