Menu

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?

Monitor REST API: Events

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

account_sid
sid<AC> Not PII

A 34 character string identifying the Account for which this Event was recorded.

actor_sid
sid<US> Not PII

If available, a 34 character string identifying the actor that caused this event. May be null.

actor_type
string Not PII

The type of actor that caused this event. For instance, 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 human-readable description of the event. May be null.

event_data
object Not PII

A freeform json object encoding additional data about the event. The exact contents will vary based on event_type. For instance, for event-types of the form RESOURCE.updated, event_data will contain a resource_properties dictionary encoding the previous and updated properties of the resource.

event_date
date_time<iso8601> Not PII

The date-time the event was recorded, given as a UTC ISO 8601 Timestamp.

event_type
string Not PII

The event's type, as a string. Event-types are typically of 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, look here.

resource_sid
sid Not PII

A 34 character string identifying 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, look here.

sid
sid<AE> Not PII

A 34 character string that uniquely identifies this event.

source
string Not PII

The originating system or interface that caused the event. web for events caused by user action in the Twilio Console. api for events caused through a request to the REST API. 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. For instance, the ip address of an originating API request. Null for events with {"source": "twilio"}

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
Sid
Required
get sid<AE> Not PII

A 34 character string that uniquely identifies this event.

Example
Loading Code Sample...
      
      
      
      

      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][4].

      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.

      [4] /docs/api/rest/response#response-formats-list-paging-information

      Parameters
      ActorSid
      Optional
      get sid<US> Not PII

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

      EndDate
      Optional
      get date_time<iso8601> Not PII

      Only show events on or before this date. Useful in combination with StartDate to define a date-range of events. Input is a UTC ISO 8601 Timestamp, but time of day is ignored by the filter.

      EventType
      Optional
      get string Not PII

      Only include Events of this EventType.

      ResourceSid
      Optional
      get sid Not PII

      Only include Events referring to this resource. Useful for discovering the history of a specific resource.

      SourceIpAddress
      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.

      StartDate
      Optional
      get date_time<iso8601> Not PII

      Only show events on or after this date. Useful in combination with EndDate to define a date-range of events. Input is a UTC ISO 8601 Timestamp, but time of day is ignored by the filter.

      Example 1
      Loading Code Sample...
          
          
          
          
          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
          Loading Code Sample...
              
              
              
              
              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
              Loading Code Sample...
                  
                  
                  
                  
                  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
                  Loading Code Sample...
                      
                      
                      
                      
                      `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

                      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.

                      Loading Code Sample...