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
| Names in REST API format | |
|---|---|
account_sid
|
The SID of the Account that created the Event resource. |
actor_sid
|
The SID of the actor that caused the event, if available. Can be |
actor_type
|
The type of actor that caused the event. Can be: |
description
|
A description of the event. Can be |
event_data
|
An object with additional data about the event. The contents depend on |
event_date
|
The date and time in GMT when the event was recorded specified in ISO 8601 format. |
event_type
|
The event's type. Event-types are typically in the form: |
resource_sid
|
The SID of the resource that was affected. |
resource_type
|
The type of resource that was affected. For a full list of all resource-types, see the Monitor Event Types. |
sid
|
The unique string that we created to identify the Event resource. |
source
|
The originating system or interface that caused the event. Can be: |
source_ip_address
|
The IP address of the source, if the source is outside the Twilio cloud. This value is |
url
|
The absolute URL of the resource that was affected. Can be |
links
|
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
https://monitor.twilio.com/v1/Events/{Sid}
Parameters
| Names in REST API format | |
|---|---|
sid
Path
|
The SID of the Event resource to fetch. |
Example
Read multiple Event resources
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 theStartDateandEndDateparameters.
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 a400 Bad Request error.
Parameters
| Names in REST API format | |
|---|---|
actor_sid
Optional
|
Only include events initiated by this Actor. Useful for auditing actions taken by specific users or API credentials. |
event_type
Optional
|
Only include events of this Event Type. |
resource_sid
Optional
|
Only include events that refer to this resource. Useful for discovering the history of a specific resource. |
source_ip_address
Optional
|
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
|
Only include events that occurred on or after this date. Specify the date in GMT and ISO 8601 format. |
end_date
Optional
|
Only include events that occurred on or before this date. Specify the date in GMT and ISO 8601 format. |
Example 1
Example 2
Example 3
Example 4
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.