Get Started

REST API: Usage Triggers

UsageTriggers are webhooks that notify your application of usage thresholds. You can set UsageTriggers for any usage category. UsageTriggers are evaluated frequently - about once a minute - so they can provide timely information to your application. In addition, UsageTriggers can be configured to recur daily, monthly, or yearly so you can create a single UsageTrigger that will track usage every day.

For instance, a UsageTrigger could notify your application if usage cost starts to exceed what you would expect in a day. Or, used in combination with Subaccounts created for each of your end-users, UsageTriggers could notify your application that a particular user has exceeded their allocated monthly usage.

The resource supports POST to make a new UsageTrigger or update an existing UsageTrigger, GET to retrieve existing UsageTriggers, and DELETE to remove an existing trigger.

Triggers Instance Resource

Resource URI

UsageTriggers are scoped under /Usage, and are referenced by their Sid.

/2010-04-01/Accounts/{AccountSid}/Usage/Triggers/{UsageTriggerSid}

Resource Properties

A UsageTrigger is represented by the following properties:

Property Description
Sid The trigger's unique Sid.
DateCreated The date the trigger was created, given as GMT RFC 2822 format.
DateUpdated The date the trigger was last updated, given as GMT RFC 2822 format.
AccountSid The account this trigger monitors.
FriendlyName A user-specified, human-readable name for the trigger.
Recurring How this trigger recurs. Empty for non-recurring triggers. One of daily, monthly, or yearly for recurring triggers. A trigger will only fire once during each recurring period. Recurring periods are in GMT.
UsageCategory The usage category the trigger watches. One of the supported usage categories.
TriggerBy The field in the UsageRecord that fires the trigger. One of count, usage, or price, as described in the UsageRecords documentation.
TriggerValue The value at which the trigger will fire. Must be a positive numeric value.
CurrentValue The current value of the field the trigger is watching.
UsageRecordUri The URI of the UsageRecord this trigger is watching, relative to https://api.twilio.com.
CallbackUrl Twilio will make a request to this url when the trigger fires.
CallbackMethod The HTTP method Twilio will use when making a request to the CallbackUrl. GET or POST.
DateFired The date the trigger was last fired, given as GMT RFC 2822 format.
Uri The URI for this resource, relative to https://api.twilio.com.

As soon as the account's usage category crosses the UsageTrigger's TriggerValue during the interval specified, then Twilio will make a request to the CallbackUrl using the HTTP method CallbackMethod with the parameters described below. Twilio guarantees that a UsageTrigger will fire at most once during its recurring interval, and will retry the callback URL 3 times quickly after a 5xx error.

HTTP GET

Returns a repesentation of the UsageTrigger, including the properties above.

Example

HTTP POST

Tries to update the UsageTrigger's properties, and returns the updated resource representation if successful. The returned response is identical to that returned when making a GET request.

Optional Parameters

You may specify one or more of the following parameters to update this UsageTrigger's properties. Note that POST parameters are case-sensitive.

Parameter Description
FriendlyName A human-readable name for the trigger.
CallbackUrl Twilio will make a request to this url when the trigger fires.
CallbackMethod The HTTP method Twilio will use when making a request to the CallbackUrl. GET or POST.

Note that it's not currently possible to update the category or value of an existing UsageTrigger. Instead, POST to create a new UsageTrigger, and DELETE to remove the old one.

Example

Change the FriendlyName and CallbackUrl.

HTTP PUT

Not supported.

HTTP DELETE

Delete this UsageTrigger.

If successful, Twilio will return an HTTP 204 response with no body.

UsageTriggers List Resource

Resource URI

The list resource for all UsageTriggers:

/2010-04-01/Accounts/{AccountSid}/Usage/Triggers

HTTP GET

Returns a list of UsageTrigger resource representations. The list includes paging information.

List Filters

By default, all UsageTriggers are returned. You can filter the list by specifying one or more query parameters. Note that the query parameters are case-sensitive:

Parameter Description
Recurring Only show UsageTriggers that count over this interval. One of daily, monthly, or yearly. To retrieve non-recurring triggers, leave this empty or use alltime.
UsageCategory Only show UsageTriggers that watch this usage category. Must be one of the supported usage categories.
TriggerBy Only show UsageTriggers that trigger by this field in the UsageRecord. Must be one of: count, usage, or price as described in the UsageRecords documentation.
Example: Get All Daily UsageTriggers for Calls

HTTP POST

Creates a new UsageTrigger. Each account can create up to 1,000 UsageTriggers. Currently, UsageTriggers that are no longer active are not deleted automatically. Use DELETE to delete triggers you no longer need.

Required Parameters

Your request must include the following parameters:

Parameter Description
UsageCategory The trigger will watch this usage category. One of the supported usage categories.
TriggerValue The trigger will fire when usage reaches this value. For convenience, you can use an offset like +30, which tells Twilio to create the UsageTrigger with its TriggerValue 30 units higher than the current usage. (just be sure to urlencode the + as %2B).
CallbackUrl Twilio will make a request to this url when the trigger fires.
Optional Parameters

Your request may include the following parameters:

Parameter Description
FriendlyName A human readable description of the new trigger. Maximum 64 characters.
TriggerBy The field in the UsageRecord that will fire the trigger. One of count, usage, or price as described in the UsageRecords documentation. The default is usage.
Recurring To make a recurring trigger that counts over its recurring interval, set this to one of: daily, monthly, or yearly. Omit this to create a non-recurring trigger.
CallbackMethod Twilio will use this HTTP method when making a request to the CallbackUrl. GET or POST. The default is POST.

If successful, Twilio responds with a representation of the new trigger.

Example

Create a new UsageTrigger that will fire when 1,000 SMS messages have been sent.

HTTP PUT

Not Supported.

HTTP DELETE

Not Supported.

UsageTrigger Callbacks

As soon as the usage value of a UsageTrigger exceeds the TriggerValue, the trigger will fire and Twilio will make an asynchronous HTTP request to the UsageTrigger's CallbackUrl. This request will typically fire within a minute of exceeding the usage threshold.

CallbackUrl Request Parameters

The parameters Twilio passes to the UsageTrigger's CallbackUrl are as follows:

Parameter Description
AccountSid Your Twilio account id. It is 34 characters long, and always starts with the letters AC.
UsageTriggerSid The unique identifier of the UsageTrigger that fired.
DateFired When the UsageTrigger fired, in GMT.
Recurring How the UsageTrigger that fired recurs. Empty for non-recurring UsageTriggers. One of daily, monthly, or yearly for recurring UsageTriggers.
UsageCategory The usage category the UsageTrigger watches. One of the supported usage categories.
TriggerBy The field in the UsageRecord that fires the UsageTrigger. One of count, usage, or price as described in the UsageRecords documentation.
TriggerValue The value at which the UsageTrigger will fire.
CurrentUsageValue The current value of the usage the UsageTrigger is watching.
UsageRecordUri The URI of the UsageRecord this UsageTrigger was watching when it fired.
IdempotencyToken A random token generated by Twilio, and guaranteed to be unique for this particular firing of this UsageTrigger. See Best Practices with Usage Trigger Callbacks.

Best Practices with Usage Trigger Callbacks

When implementing a handler for UsageTrigger's CallbackUrl it is possible that your handler may receive HTTP requests more than once. Services that handle duplicate requests and return the same response are called idempotent. We give you an IdempotencyToken that is unique for each Usage Trigger callback.

Example of a Recurring daily Usage Trigger's IdempotencyToken fired on 2012-10-04:
ACed70abd024d3f57a4027b5dc2ca88d5b-FIRES-UTc142bed7b38c4f8186ef41a309814fd2-2012-10-04

You can keep track of the IdempotencyToken to properly handle requests to your service and prevent them from performing same operation twice. For instance, your callback service may send billing notifications via email. For the best possible customer experience, you would want your customer's to only receive the billing notification email once.

You can follow the test-and-set pattern to implement idempotent services. In short, you would test for the existence of the IdempotencyToken before processing your application's logic. This allows your application to handle already existing tokens and choose the next appropriate step. In the email example, you would have had already sent the email to your customer, then you would just skip sending the email and reply with an HTTP status code of 200.