Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Monitor Event Resource


Events is 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.
  • 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. 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

event-properties page anchor
Resource properties
account_sidtype: SID<AC>Not PII

actor_sidtype: SID<US>Not PII

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


actor_typetype: stringNot 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.


descriptiontype: stringNot PII

A description of the event. Can be null.


event_datatype: objectNot 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_datetype: string<DATE TIME>Not PII

The date and time in GMT when the event was recorded specified in ISO 8601(link takes you to an external page) format.


event_typetype: stringNot 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(link takes you to an external page).


resource_sidtype: SIDNot PII

The SID of the resource that was affected.


resource_typetype: stringNot PII

The type of resource that was affected. For a full list of all resource-types, see the Monitor Event Types(link takes you to an external page).


sidtype: SID<AE>Not PII

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


sourcetype: stringNot 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_addresstype: stringNot 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


urltype: string<URI>Not PII

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


linkstype: object<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 page anchor

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:

sourceactor_typeactor_siddescription
apiaccountAC123The Account AC123 authenticated against the API and caused the event.
webuserUS456The 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(link takes you to an external page) of the Twilio Console.
twiliotwilio-adminnullA Twilio Administrator made the change through Twilio's administration interface.

GET https://monitor.twilio.com/v1/Events/{Sid}

Parameters

fetch-parameters page anchor
URI parameters
Sidtype: SID<AE>Not PII
Path Parameter

The SID of the Event resource to fetch.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.monitor.v1.events('AEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.fetch()
_10
.then(event => console.log(event.actorSid));

Output

_24
{
_24
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"actor_sid": "USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"actor_type": "account",
_24
"description": null,
_24
"event_data": {
_24
"friendly_name": {
_24
"previous": "SubAccount Created at 2014-10-03 09:48 am",
_24
"updated": "Mr. Friendly"
_24
}
_24
},
_24
"event_date": "2014-10-03T16:48:25Z",
_24
"event_type": "account.updated",
_24
"links": {
_24
"actor": "https://api.twilio.com/2010-04-01/Accounts/USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"resource": "https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_24
},
_24
"resource_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"resource_type": "account",
_24
"sid": "AEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"source": "api",
_24
"source_ip_address": "10.86.6.250",
_24
"url": "https://monitor.twilio.com/v1/Events/AEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_24
}


Read multiple Event resources

read-multiple-event-resources page anchor
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.

URI parameters
ActorSidtype: SID<US>Not PII
Query Parameter

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


EventTypetype: stringNot PII
Query Parameter

ResourceSidtype: SIDNot PII
Query Parameter

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


SourceIpAddresstype: stringNot PII
Query Parameter

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


StartDatetype: string<DATE TIME>Not PII
Query Parameter

Only include events that occurred on or after this date. Specify the date in GMT and ISO 8601(link takes you to an external page) format.


EndDatetype: string<DATE TIME>Not PII
Query Parameter

Only include events that occurred on or before this date. Specify the date in GMT and ISO 8601(link takes you to an external page) format.


PageSizetype: integerNot PII
Query Parameter

How many resources to return in each list page. The default is 50, and the maximum is 1000.


Pagetype: integerNot PII
Query Parameter

The page index. This value is simply for client state.


PageTokentype: stringNot PII
Query Parameter

The page token. This is provided by the API.

An example that filters for all events in March, 2015

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_14
// Download the helper library from https://www.twilio.com/docs/node/install
_14
// Find your Account SID and Auth Token at twilio.com/console
_14
// and set the environment variables. See http://twil.io/secure
_14
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14
const authToken = process.env.TWILIO_AUTH_TOKEN;
_14
const client = require('twilio')(accountSid, authToken);
_14
_14
client.monitor.v1.events
_14
.list({
_14
endDate: new Date(Date.UTC(2015, 3, 1, 0, 0, 0)),
_14
startDate: new Date(Date.UTC(2015, 2, 1, 0, 0, 0)),
_14
limit: 20
_14
})
_14
.then(events => events.forEach(e => console.log(e.sid)));

Output

_37
{
_37
"events": [
_37
{
_37
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"actor_sid": "USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"actor_type": "account",
_37
"description": null,
_37
"event_data": {
_37
"friendly_name": {
_37
"previous": "SubAccount Created at 2014-10-03 09:48 am",
_37
"updated": "Mr. Friendly"
_37
}
_37
},
_37
"event_date": "2014-10-03T16:48:25Z",
_37
"event_type": "account.updated",
_37
"links": {
_37
"actor": "https://api.twilio.com/2010-04-01/Accounts/USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"resource": "https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_37
},
_37
"resource_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"resource_type": "account",
_37
"sid": "AEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"source": "api",
_37
"source_ip_address": "10.86.6.250",
_37
"url": "https://monitor.twilio.com/v1/Events/AEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_37
}
_37
],
_37
"meta": {
_37
"first_page_url": "https://monitor.twilio.com/v1/Events?PageSize=50&Page=0",
_37
"key": "events",
_37
"next_page_url": "https://monitor.twilio.com/v1/Events?PageSize=50&Page=1",
_37
"page": 0,
_37
"page_size": 50,
_37
"previous_page_url": "https://monitor.twilio.com/v1/Events?PageSize=50&Page=0",
_37
"url": "https://monitor.twilio.com/v1/Events?PageSize=50&Page=0"
_37
}
_37
}

Filter for a phone number

filter-for-a-phone-number page anchor

Using the Events list resource and the ResourceSid filter to find out everything that happened a a specific phone-number

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_13
// Download the helper library from https://www.twilio.com/docs/node/install
_13
// Find your Account SID and Auth Token at twilio.com/console
_13
// and set the environment variables. See http://twil.io/secure
_13
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_13
const authToken = process.env.TWILIO_AUTH_TOKEN;
_13
const client = require('twilio')(accountSid, authToken);
_13
_13
client.monitor.v1.events
_13
.list({
_13
resourceSid: 'PN4aa51b930717ea83c91971b86d99018f',
_13
limit: 20
_13
})
_13
.then(events => events.forEach(e => console.log(e.sid)));

Output

_37
{
_37
"events": [
_37
{
_37
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"actor_sid": "USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"actor_type": "account",
_37
"description": null,
_37
"event_data": {
_37
"friendly_name": {
_37
"previous": "SubAccount Created at 2014-10-03 09:48 am",
_37
"updated": "Mr. Friendly"
_37
}
_37
},
_37
"event_date": "2014-10-03T16:48:25Z",
_37
"event_type": "account.updated",
_37
"links": {
_37
"actor": "https://api.twilio.com/2010-04-01/Accounts/USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"resource": "https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_37
},
_37
"resource_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"resource_type": "account",
_37
"sid": "AEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"source": "api",
_37
"source_ip_address": "10.86.6.250",
_37
"url": "https://monitor.twilio.com/v1/Events/AEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_37
}
_37
],
_37
"meta": {
_37
"first_page_url": "https://monitor.twilio.com/v1/Events?PageSize=50&Page=0",
_37
"key": "events",
_37
"next_page_url": "https://monitor.twilio.com/v1/Events?PageSize=50&Page=1",
_37
"page": 0,
_37
"page_size": 50,
_37
"previous_page_url": "https://monitor.twilio.com/v1/Events?PageSize=50&Page=0",
_37
"url": "https://monitor.twilio.com/v1/Events?PageSize=50&Page=0"
_37
}
_37
}

Filter for an IP address

filter-for-an-ip-address page anchor

Using the SourceIpAddress filter to track the activity of a particular IP address on a day in April

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_15
// Download the helper library from https://www.twilio.com/docs/node/install
_15
// Find your Account SID and Auth Token at twilio.com/console
_15
// and set the environment variables. See http://twil.io/secure
_15
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_15
const authToken = process.env.TWILIO_AUTH_TOKEN;
_15
const client = require('twilio')(accountSid, authToken);
_15
_15
client.monitor.v1.events
_15
.list({
_15
endDate: new Date(Date.UTC(2015, 3, 25, 0, 0, 0)),
_15
sourceIpAddress: '104.14.155.29',
_15
startDate: new Date(Date.UTC(2015, 3, 25, 0, 0, 0)),
_15
limit: 20
_15
})
_15
.then(events => events.forEach(e => console.log(e.sid)));

Output

_37
{
_37
"events": [
_37
{
_37
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"actor_sid": "USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"actor_type": "account",
_37
"description": null,
_37
"event_data": {
_37
"friendly_name": {
_37
"previous": "SubAccount Created at 2014-10-03 09:48 am",
_37
"updated": "Mr. Friendly"
_37
}
_37
},
_37
"event_date": "2014-10-03T16:48:25Z",
_37
"event_type": "account.updated",
_37
"links": {
_37
"actor": "https://api.twilio.com/2010-04-01/Accounts/USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"resource": "https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_37
},
_37
"resource_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"resource_type": "account",
_37
"sid": "AEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"source": "api",
_37
"source_ip_address": "10.86.6.250",
_37
"url": "https://monitor.twilio.com/v1/Events/AEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_37
}
_37
],
_37
"meta": {
_37
"first_page_url": "https://monitor.twilio.com/v1/Events?PageSize=50&Page=0",
_37
"key": "events",
_37
"next_page_url": "https://monitor.twilio.com/v1/Events?PageSize=50&Page=1",
_37
"page": 0,
_37
"page_size": 50,
_37
"previous_page_url": "https://monitor.twilio.com/v1/Events?PageSize=50&Page=0",
_37
"url": "https://monitor.twilio.com/v1/Events?PageSize=50&Page=0"
_37
}
_37
}

Only use one filter property at a time!

only-use-one-filter-property-at-a-time page anchor

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

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_14
// Download the helper library from https://www.twilio.com/docs/node/install
_14
// Find your Account SID and Auth Token at twilio.com/console
_14
// and set the environment variables. See http://twil.io/secure
_14
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14
const authToken = process.env.TWILIO_AUTH_TOKEN;
_14
const client = require('twilio')(accountSid, authToken);
_14
_14
client.monitor.v1.events
_14
.list({
_14
actorSid: 'USd0afd67cddff4ec7cb0022771a203cb1',
_14
resourceSid: 'PN4aa51b930717ea83c91971b86d99018f',
_14
limit: 20
_14
})
_14
.then(events => events.forEach(e => console.log(e.sid)));

Output

_37
{
_37
"events": [
_37
{
_37
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"actor_sid": "USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"actor_type": "account",
_37
"description": null,
_37
"event_data": {
_37
"friendly_name": {
_37
"previous": "SubAccount Created at 2014-10-03 09:48 am",
_37
"updated": "Mr. Friendly"
_37
}
_37
},
_37
"event_date": "2014-10-03T16:48:25Z",
_37
"event_type": "account.updated",
_37
"links": {
_37
"actor": "https://api.twilio.com/2010-04-01/Accounts/USXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"resource": "https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_37
},
_37
"resource_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"resource_type": "account",
_37
"sid": "AEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_37
"source": "api",
_37
"source_ip_address": "10.86.6.250",
_37
"url": "https://monitor.twilio.com/v1/Events/AEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_37
}
_37
],
_37
"meta": {
_37
"first_page_url": "https://monitor.twilio.com/v1/Events?PageSize=50&Page=0",
_37
"key": "events",
_37
"next_page_url": "https://monitor.twilio.com/v1/Events?PageSize=50&Page=1",
_37
"page": 0,
_37
"page_size": 50,
_37
"previous_page_url": "https://monitor.twilio.com/v1/Events?PageSize=50&Page=0",
_37
"url": "https://monitor.twilio.com/v1/Events?PageSize=50&Page=0"
_37
}
_37
}

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

Events currently tracks the following resource types and associated event types. All of the event types are available via the console and API:

Resource TypeEvent Types
accountaccount.created account.updated account.deleted
account-api-keysaccount-api-keys.created account-api-keys.deleted account-api-keys.updated
account-auth-tokenaccount-auth-token.deleted account-auth-token.promoted account-auth-token.updated account-auth-token.created account-auth-token.secondary-created account-auth-token.secondary-deleted
account-credentialsaccount-credentials.created account-credentials.deleted account-credentials.updated
account-keysaccount-keys.created account-keys.deleted account-keys.updated
applicationapplication.created application.updated application.deleted
authorized-connect-appauthorized-connect-app.created authorized-connect-app.deleted authorized-connect-app.updated
bulkexportsbulkexports.created bulkexports.deleted bulkexports.downloaded bulkexports.updated
byoc-trunkbyoc-trunk.updated byoc-trunk.created byoc-trunk.deleted
callcall.deleted
call.statuscall.status.updated
caller-idcaller-id.created caller-id.updated caller-id.deleted
configconfig.created config.deleted config.updated
connect-appconnect-app.created connect-app.updated connect-app.deleted
connection-policyconnection-policy.created connection-policy.deleted connection-policy.updated
copilot-applicationcopilot-application.created copilot-application.updated copilot-application.deleted
copilot-number-poolcopilot-number-pool.created copilot-number-pool.deleted copilot-number-pool.updated
data-access-policydata-access-policy.updated
data-policydata-policy.created data-policy.updated data-policy.deleted
interconnect-connectioninterconnect-connection.created interconnect-connection.updated interconnect-connection.deleted
invoice-settingsinvoice-settings.created invoice-settings.deleted invoice-settings.updated
ip-access-control-listip-access-control-list.created ip-access-control-list.deleted ip-access-control-list.updated
ip-messaging.channelip-messaging.channel.created ip-messaging.channel.updated ip-messaging.channel.deleted
ip-messaging.credentialip-messaging.credential.created ip-messaging.credential.updated ip-messaging.credential.deleted
ip-messaging.memberip-messaging.member.created ip-messaging.member.updated ip-messaging.member.deleted
ip-messaging.messageip-messaging.message.created ip-messaging.message.deleted ip-messaging.message.updated
ip-messaging.roleip-messaging.role.created ip-messaging.role.updated ip-messaging.role.deleted
ip-messaging.serviceip-messaging.service.created ip-messaging.service.updated ip-messaging.service.deleted
ip-messaging.userip-messaging.user.deleted ip-messaging.user.created ip-messaging.user.updated
ip-recordip-record.created ip-record.updated ip-record.deleted
messagemessage.updated message.deleted
message-bodymessage-body.deleted
message-mediamessage-media.deleted message-media.deletedall message-media.created message-media.updated
messaging-settingsmessaging-settings.updated
paymentpayment.created payment.deleted payment.updated
payment-methodpayment-method.created payment-method.updated payment-method.deleted
payment-refundpayment-refund.created payment-refund.deleted payment-refund.updated
phone-numberphone-number.created phone-number.updated phone-number.deleted
recharge-triggerrecharge-trigger.created recharge-trigger.updated recharge-trigger.deleted
recordingrecording.created recording.updated recording.deleted recording.bulk-delete.created recording.accessed
reportreport.cloned report.updated
rtc-app-configrtc-app-config.created rtc-app-config.updated rtc-app-config.deleted
security-settingssecurity-settings.created security-settings.deleted security-settings.updated
sender-idsender-id.created sender-id.updated sender-id.deleted sender-id.country.created sender-id.country.deleted sender-id.country.status.updated sender-id.country.override_status.updated sender-id.registration.added sender-id.registration.removed
service
service-recordservice-record.created service-record.updated service-record.deleted
shortcodeshortcode.created shortcode.updated shortcode.deleted
sipmanipulationsipmanipulation.created sipmanipulation.updated sipmanipulation.deleted
sip-credential-listsip-credential-list.created sip-credential-list.updated sip-credential-list.deleted
sip-domainsip-domain.created sip-domain.updated sip-domain.deleted
sip-ip-access-control-listsip-ip-access-control-list.created sip-ip-access-control-list.updated sip-ip-access-control-list.deleted
slapchop-apislapchop-api.created slapchop-api.updated slapchop-api.deleted
sms-geographic-permissionssms-geographic-permissions.created sms-geographic-permissions.deleted sms-geographic-permissions.updated
support-plansupport-plan.updated support-plan.created support-plan.deleted
taskrouter-rate-limittaskrouter-rate-limit.updated
transcriptiontranscription.created transcription.deleted transcription.accessed
trunktrunk.created trunk.deleted trunk.updated
usage-triggerusage-trigger.created usage-trigger.updated usage-trigger.deleted
useruser.created user.deleted user.updated
user-invitationuser-invitation.created user-invitation.deleted user-invitation.updated
user-passworduser-password.created user-password.deleted user-password.updated
user-sessionuser-session.created user-session.deleted user-session.updated
verify-fraud-guardverify-fraud-guard.updated
verify-fraud-guard-modeverify-fraud-guard-mode.updated
verify-geo-permissions-smsverify-geo-permissions-sms.updated
verify-geo-permissions-voiceverify-geo-permissions-voice.updated
voice-geographic-permissionsvoice-geographic-permissions.created voice-geographic-permissions.deleted voice-geographic-permissions.updated
voice-insights-account-flagsvoice-insights-account-flags.updated
voice-tracevoice-trace.updated
wireless-simwireless-sim.updated
wireless-sim.connectionwireless-sim.connection.updated

Rate this page: