Menu

Expand
Rate this page:

Monitor Event Resource

Events are a platform feature that provides comprehensive event-logging and change-tracking for Twilio resources.

For example, Events log when you provision a phone number, change your account's security settings, delete a recording, and so on. Events log virtually every action taken within Twilio, regardless of whether that action was taken through the API, by a user in the Twilio Console, or even by a Twilio employee.

The Events REST resource provides an API to retrieve this event-log. Each Event is like a log entry that captures:

  • the type of event;
  • the resource that the event relates to;
  • the actor that caused the event to happen;
  • the originating source for the event, including its IP address; and
  • any related event data (like what properties were changed).

Events work at any scale and across all Twilio products. They can be an instrumental tool in giving you full visibility into your Twilio applications. And the API can be used to retrieve your event log and push it into the log-aggregation or SIEM solution of your choice.

Event properties

Resource Properties in REST API format
account_sid
sid<AC> Not PII

The SID of the Account that created the Event resource.

actor_sid
sid<US> Not PII

The SID of the actor that caused the event, if available. Can be null.

actor_type
string Not PII

The type of actor that caused the event. Can be: user for a change made by a logged-in user in the Twilio Console, account for an event caused by an API request by an authenticating Account, twilio-admin for an event caused by a Twilio employee, and so on.

description
string Not PII

A description of the event. Can be null.

event_data
object Not PII

An object with additional data about the event. The contents depend on event_type. For example, event-types of the form RESOURCE.updated, this value contains a resource_properties dictionary that describes the previous and updated properties of the resource.

event_date
date_time<iso8601> Not PII

The date and time in GMT when the event was recorded specified in ISO 8601 format.

event_type
string Not PII

The event's type. Event-types are typically in the form: RESOURCE_TYPE.ACTION, where RESOURCE_TYPE is the type of resource that was affected and ACTION is what happened to it. For example, phone-number.created. For a full list of all event-types, see the Monitor Event Types.

resource_sid
sid Not PII

The SID of the resource that was affected.

resource_type
string Not PII

The type of resource that was affected. For a full list of all resource-types, see the Monitor Event Types.

sid
sid<AE> Not PII

The unique string that we created to identify the Event resource.

source
string Not PII

The originating system or interface that caused the event. Can be: web for events caused by user action in the Twilio Console, api for events caused by a request to our API, or twilio for events caused by an automated or internal Twilio system.

source_ip_address
string Not PII

The IP address of the source, if the source is outside the Twilio cloud. This value is null for events with source of twilio

url
url Not PII

The absolute URL of the resource that was affected. Can be null.

links
uri_map Not PII

The absolute URLs of related resources.

These fields make it easy to build Event notifications or list pages. For example, you can display human-readable strings like "On {event_date}, a {event_type} event was generated for resource {resource_type} via {source} by {actor_type} {actor_sid} from {source_ip_address}".

Sources, Actor-Types, and Actor-Sids

Sources, actor-types, and actor-sids are closely interrelated. They all help to indicate who or what caused the event, and from where. Here's a table describing the most common combinations you're likely to see:

source actor_type actor_sid description
api account AC123 The Account AC123 authenticated against the API and caused the event.
web user US456 The User whose sid is US456 was logged in the Twilio Console and caused the event. The User’s Sid can be seen in the Manager Users page of the Twilio Console.
twilio twilio-admin null A Twilio Administrator made the change through Twilio’s administration interface.

Fetch an Event resource

get
https://monitor.twilio.com/v1/Events/{Sid}
Parameters
Parameters in REST API format
sid
Path
get sid<AE> Not PII

The SID of the Event resource to fetch.

Example 1
        
        
        
        

        Read multiple Event resources

        get
        https://monitor.twilio.com/v1/Events

        Returns a list of Events in this account, sorted by event-date. This list includes paging information.

        By default, all Events are included. You can always filter your
        Events by event-date using the StartDate and EndDate parameters.

        In addition, you may filter by any one of the other fields. Filtering on more than one field in the same request is not supported and will result in a
        400 Bad Request error.

        Parameters
        Parameters in REST API format
        actor_sid
        Optional
        get sid<US> Not PII

        Only include events initiated by this Actor. Useful for auditing actions taken by specific users or API credentials.

        event_type
        Optional
        get string Not PII

        Only include events of this Event Type.

        resource_sid
        Optional
        get sid Not PII

        Only include events that refer to this resource. Useful for discovering the history of a specific resource.

        source_ip_address
        Optional
        get string Not PII

        Only include events that originated from this IP address. Useful for tracking suspicious activity originating from the API or the Twilio Console.

        start_date
        Optional
        get date_time<iso8601> Not PII

        Only include events that occurred on or after this date. Specify the date in GMT and ISO 8601 format.

        end_date
        Optional
        get date_time<iso8601> Not PII

        Only include events that occurred on or before this date. Specify the date in GMT and ISO 8601 format.

        Example 1
              
              
              
              
              An example that filters for all events in March, 2015

              Filter by date

              An example that filters for all events in March, 2015
              Example 2
                    
                    
                    
                    
                    Using the Events list resource and the `ResourceSid` filter to find out everything that happened a a specific phone-number

                    Filter for a phone number

                    Using the Events list resource and the `ResourceSid` filter to find out everything that happened a a specific phone-number
                    Example 3
                          
                          
                          
                          
                          Using the `SourceIpAddress` filter to track the activity of a particular IP address on a day in April

                          Filter for an IP address

                          Using the `SourceIpAddress` filter to track the activity of a particular IP address on a day in April
                          Example 4
                                
                                
                                
                                
                                `ActorSid`, `ResourceSid`, and `SourceIpAddress` may only be used one-at-a-time, so this request that uses both `ActorSid` and `ResourceSid` returns an HTTP 400 error

                                Only use one filter property at a time!

                                `ActorSid`, `ResourceSid`, and `SourceIpAddress` may only be used one-at-a-time, so this request that uses both `ActorSid` and `ResourceSid` returns an HTTP 400 error

                                Full List of All Supported Resource-Types and Event-Types

                                Events currently tracks the following resource types and associated event types:

                                Resource Type Event Types
                                account account.created
                                account.updated
                                account.deleted
                                application application.created
                                application.updated
                                application.deleted
                                authorized-connect-app authorized-connect-app.created
                                authorized-connect-app.deleted
                                call call.deleted
                                caller-id caller-id.created
                                caller-id.updated
                                caller-id.deleted
                                connect-app connect-app.created
                                connect-app.updated
                                connect-app.deleted
                                invoice-settings invoice-settings.updated
                                message message.updated
                                message.deleted
                                message-body message-body.deleted
                                message-media message-media.deleted
                                payment payment.created
                                payment-method payment-method.created
                                payment-method.updated
                                payment-method.deleted
                                payment-refund payment-refund.created
                                phone-number phone-number.created
                                phone-number.updated
                                phone-number.deleted
                                recharge-trigger recharge-trigger.created
                                recharge-trigger.updated
                                recharge-trigger.deleted
                                recording recording.deleted
                                shortcode shortcode.created
                                shortcode.updated
                                shortcode.deleted
                                sip-credential-list sip-credential-list.created
                                sip-credential-list.updated
                                sip-credential-list.deleted
                                sip-domain sip-domain.created
                                sip-domain.updated
                                sip-domain.deleted
                                sip-ip-access-control-list sip-ip-access-control-list.created
                                sip-ip-access-control-list.updated
                                sip-ip-access-control-list.deleted
                                support-plan support-plan.updated
                                sms-geographic-permissions sms-geographic-permissions.updated
                                transcription transcription.deleted
                                usage-trigger usage-trigger.created
                                usage-trigger.updated
                                usage-trigger.deleted
                                voice-geographic-permissions voice-geographic-permissions.updated
                                wireless-sim wireless-sim.updated

                                Resource-Types and Event-Types Available only via the Console

                                All of the above event types are available via the console and API. The following types can be viewed in the console only:

                                Resource Type Event Types
                                account-api-keys account-api-keys.created
                                account-api-keys.deleted
                                account-api-keys.updated
                                account-auth-token account-auth-token.created
                                account-auth-token.deleted
                                account-auth-token.updated
                                account-credentials account-credentials.created
                                account-credentials.deleted
                                account-credentials.updated
                                authorized-connect-app authorized-connect-app.created
                                authorized-connect-app.deleted
                                authorized-connect-app.updated
                                config config.created
                                config.deleted
                                connect-app connect-app.created
                                connect-app.deleted
                                connect-app.updated
                                connection-policy connection-policy.created
                                connection-policy.deleted
                                connection-policy.updated
                                copilot-application copilot-application.created
                                copilot-application.updated
                                copilot-application.deleted
                                copilot-number-pool copilot-number-pool.created
                                copilot-number-pool.deleted
                                copilot-number-pool.updated
                                data-policy data-policy.created
                                data-policy.deleted
                                invoice-settings invoice-settings.created
                                invoice-settings.deleted
                                ip-access-control-list ip-access-control-list.created
                                ip-access-control-list.deleted
                                ip-access-control-list.updated
                                ip-messaging ip-messaging.message.deleted
                                ip-messaging.message.updated
                                message-body message-body.updated
                                payment-refund payment-refund.deleted
                                payment-refund.updated
                                payment payment.deleted
                                payment.updated
                                security-settings security-settings.created
                                security-settings.deleted
                                security-settings.updated
                                sms-geographic-permissions sms-geographic-permissions.created
                                sms-geographic-permissions.deleted
                                support-plan support-plan.created
                                support-plan.deleted
                                transcription transcription.created
                                transcription.updated
                                user-invitation user-invitation.created
                                user-invitation.deleted
                                user-invitation.updated
                                user-password user-password.created
                                user-password.deleted
                                user-password.updated
                                user-session user-session.created
                                user-session.deleted
                                user-session.updated
                                user user.created
                                user.deleted
                                user.updated
                                voice-geographic-permissions voice-geographic-permissions.created
                                voice-geographic-permissions.deleted
                                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.

                                      
                                      
                                      

                                      Thank you for your feedback!

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

                                      Sending your feedback...
                                      🎉 Thank you for your feedback!
                                      Something went wrong. Please try again.

                                      Thanks for your feedback!

                                      Refer us and get $10 in 3 simple steps!

                                      Step 1

                                      Get link

                                      Get a free personal referral link here

                                      Step 2

                                      Give $10

                                      Your user signs up and upgrade using link

                                      Step 3

                                      Get $10

                                      1,250 free SMSes
                                      OR 1,000 free voice mins
                                      OR 12,000 chats
                                      OR more