REST API: 使用状況記録 (Usage Records)
UsageRecords RESTリソースは、 任意の期間中、および任意の利用カテゴリーにおけるお手持ちのTwilioアカウントの使用状況を取得するシンプルなAPIを提供します。 これにより、アプリケーション用のレポートや分析ツールの作成が簡単になります。
UsageRecords used in combination with Subaccounts created for each of your end-users make it possible to build recurring usage-based billing systems on top of Twilio’s API with just a few simple API calls. If rectifying UsageRecords with billing, see our dedicated article.
Usage Triggers をセットすれば、日・月・年 をはじめとした様々な時間軸で、特定のカテゴリの利用が、予め設定した閾値を超えた際に、通知をだすことができます。トリガーは、エンドユーザーがその使用上限に達した場合や、アプリケーションのリクエストが制御不能に陥った場合を判断するのに役立てることができます。
UsageRecord properties
This resource and its subresources always return a list of UsageRecords. Each UsageRecord is represented by the following properties:
| Resource Properties in REST API format | |
|---|---|
account_sid
|
The SID of the Account that accrued the usage. |
api_version
|
The API version used to create the resource. |
as_of
|
Usage records up to date as of this timestamp, formatted as YYYY-MM-DDTHH:MM:SS+00:00. All timestamps are in GMT |
category
|
The category of usage. For more information, see Usage Categories. |
count
|
The number of usage events, such as the number of calls. |
count_unit
|
The units in which |
description
|
A plain-language description of the usage category. |
end_date
|
The last date for which usage is included in the UsageRecord. The date is specified in GMT and formatted as |
price
|
The total price of the usage in the currency specified in |
price_unit
|
The currency in which |
start_date
|
The first date for which usage is included in this UsageRecord. The date is specified in GMT and formatted as |
subresource_uris
|
A list of related resources identified by their URIs. For more information, see List Subresources. |
uri
|
The URI of the resource, relative to |
usage
|
The amount used to bill usage and measured in units described in |
usage_unit
|
The units in which |
Usage、Count、Price プロパティ
Each UsageRecord contains three amounts: Usage, Count, and Price. Usage is the primary way usage is measured for that category: minutes for calls, messages for SMS, etc. Count is the number of usage events: calls for calls, etc. Price is the price of the usage in the currency associated with the account.
それぞれの利用記録には、利用量の記録に用いる単位を示すフィールドがあります。たとえば、Usage の単位は UsageUnit です。 これらのフィールドを使って、利用一覧を表示するダッシュ ボードを簡単に作成することができます。 たとえばこれらのパラメーターを次のように変数に代入して組み合わせると、人間が読みやすい形式の文字列で利用状況を表すことができます。 「$Usage $UsageUnits (1分、3時間、など) 」、「$Count $CountUnits (25個、など) 」、「$Price $PriceUnits (500JPY、2USD、など) 」
利用カテゴリー
A UsageRecord’s Category defines the type of usage it represents. The full list of all categories is here, but you’ll usually focus on just a few common categories:
| Category | 概要 |
|---|---|
| calls | Inbound and outbound voice calls. Does not include SIP or client calls. Count is the number of calls and Usage is the number of minutes. |
| sms | すべての SMS メッセージです。Count と Usage は、いずれも送信したメッセージの件数です。 |
| pfax-minutes | Programmable Fax minutes. Count is the number of faxes and Usage is the number of minutes. |
| pfax-pages | Programmable Fax pages. Count is the number of faxes and Usage is the number of pages. |
| phonenumbers | このアカウントが所有するすべての電話番号です。 |
| recordings | 音声通話の録音です。Count は録音件数、Usage は録音分数です。 |
| transcriptions | 音声通話のトランスクリプションです。Count はトランスクリプションの件数、Usage はテキスト化された音声の分数です。 |
| pv | All Programmable Video usage including TURN. Price accounts for expenses in all Programmable Video products. Count and Usage should be ignored. |
| totalprice | すべての利用の合計金額です。Usage は Price と同じになります。Count は空になります。 Twilio の利用料金にはどの利用カテゴリーにも当てはまらないものがあり、すべての利用記録の Price の合計が TotalPrice の Price と一致しない場合がありますので、注意してください。 |
Read multiple UsageRecord resources
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Usage/Records.json
デフォルトでは、UsageRecord リソースは、Category ごとに 1 つの利用記録を返します。この利用記録は、アカウントに課金されたすべての利用を対象とし、期間の指定はありません。 利用を Category でフィルターするか、またはオプションの GET クエリ パラメーターを使用して、利用をカウントする日付の範囲を変更できます。 クエリ パラメーターの大文字と小文字は区別されますので、注意してください。
パラメーター
| Parameters in REST API format | |
|---|---|
account_sid
Path
|
The SID of the Account that created the UsageRecord resources to read. |
category
オプション
|
The usage category of the UsageRecord resources to read. Only UsageRecord resources in the specified category are retrieved. |
start_date
オプション
|
Only include usage that has occurred on or after this date. Specify the date in GMT and format as |
end_date
オプション
|
Only include usage that occurred on or before this date. Specify the date in GMT and format as |
include_subaccounts
オプション
|
Whether to include usage from the master account and all its subaccounts. Can be: |
例 1
例 2
例 3
例 4
例 5
たとえば、2012 年 4 月のすべての利用記録をリクエストするとします。 ここではクエリ文字列は StartDate=2012-04-01&EndDate=2012-04-30 です。 4 月中の利用について、利用種別につき 1 つの利用記録が返ります。このリストは ページ情報を含みます。 後述の 例 2 を参照してください。
It’s also possible to group usage by day, by month, or by year using the subresources described below.
リスト サブリソース
メインの UsageRecords リスト リソースは、さまざまなサブリソースをサポートしており、便利に使えます。 原則として、次の形式を取ります。
/2010-04-01/Accounts/{AccountSid}/Usage/Records/{Subresource}
サポートするサブリソースは、次の通りです。
| サブリソース | 概要 |
|---|---|
| Daily | 利用カテゴリーごとに、複数の利用記録を返します。各項目は 1 日の利用を表現します。 |
| Monthly | 利用カテゴリーごとに、複数の利用記録を返します。各項目は 1 か月の利用を表現します。 |
| Yearly | 利用カテゴリーごとに、複数の利用記録を返します。各項目は 1 年の利用を表現します。 |
| AllTime | 利用カテゴリーごとに、1 つの利用記録を返します。各項目は指定された日付範囲の利用を表現します。 root /Usage/Records と同じです。 |
| Today | Return a single UsageRecord per usage category, for today’s usage only. |
| Yesterday | Return a single UsageRecord per usage category, for yesterday’s usage only. |
| ThisMonth | Return a single UsageRecord per usage category, for this month’s usage only. |
| LastMonth | Return a single UsageRecord per usage category, for last month’s usage only. |
These convenience subresources can be used to draw a graph of daily calls, display dashboards of monthly usage across all usage categories, or build a simple usage-based billing system based on last month’s usage totals.
すべてのサブリソースは、ルートの UsageCounter リソースと同じ リスト フィルター をサポートします。
すべての利用カテゴリーの完全なリスト
Voice
| Category | 概要 |
|---|---|
| answering-machine-detection | All answering machine detection recognitions for outbound calls. Count is the number of recognitions. |
| calls | Inbound and outbound voice calls. Count is the number of calls and Usage is the number of minutes. Does not include client or SIP calls. |
| calls-inbound | 携帯電話番号、無料電話番号、およびローカル番号へのすべてのインバウンド音声通話です。 |
| calls-inbound-local | 国内番号への、すべての着信音声通話です。 |
| calls-inbound-mobile | 携帯電話番号へのすべてのインバウンド音声通話です。 |
| calls-inbound-tollfree | 無料電話番号への、すべての着信音声通話です。 |
| calls-outbound | すべての発信音声通話です。 |
| calls-sip | すべてのSIPコール |
| calls-sip-inbound | すべてのインバウンド SIP 通話です。 |
| calls-sip-outbound | すべてのアウトバウンド SIP 通話です。 |
| calls-client | すべてのTiwlio クライアント音声通話です。 |
| calls-globalconference | すべてのグローバルカンファレンス通話 |
| calls-media-stream-minutes | All Media Stream calls |
| calls-pay-verb-transactions | |
| call-progess-events | すべてのコールプログレスイベントです。 |
| calls-recordings | 音声通話の録音です。Count は録音件数、Usage は録音分数です。 |
| programmablevoice-platform | All Programmable Voice Platform usage in Flex Projects |
| programmablevoiceconnectivity | Inbound and outbound voice calls in Flex Projects. Count is the number of calls and Usage is the number of minutes. Includes Client and SIP Calls. |
| programmablevoiceconn-sip | All SIP Calls in Flex Projects |
| programmablevoiceconn-sip-inbound | All Inbound SIP Calls in Flex Projects |
| programmablevoiceconn-sip-outbound | All Outbound SIP Calls in Flex Projects |
| programmablevoiceconn-clientsdk | All TwilioClient voice calls in Flex Projects |
| pstnconnectivity | Inbound and outbound voice calls in Flex Projects. Count is the number of calls and Usage is the number of minutes. |
| pstnconnectivity-inbound | All inbound voice calls, to mobile, toll-free and local numbers in Flex Projects |
| pstnconnectivity-outbound | All oubound voice calls in Flex Projects |
| recordings | 音声通話とトランク通話の録音です。Count は録音件数、Usage は録音分数です。 |
| recordingstorage | このアカウントで保存された通話の録音が使用する保存容量です。Count は保存された録音の件数、Usage は保存された録音の分数、Price は録音の保存料金です。 |
| speech-recognition | Speech recogntions in calls. Count is total number of calls where speech recognition was performed and usage is total number of recognitions |
| transcriptions | 音声通話のトランスクリプションです。Count はトランスクリプションの件数、Usage はテキスト化された音声の分数です。 |
| voice-insights | Voice Insights Advanced Features |
| voice-insights-ptsn-insights-on-demand-minute | Voice Insights Advanced Features for Programmable Voice calls |
| voice-insights-sip-trunking-insights-on-demand-minute | Voice Insights Advanced Features for Elastic SIP Trunking calls. |
SMS & MMS
| Category | 概要 |
|---|---|
| sms | 着信と発信の両方のすべての SMS メッセージです。Count と Usage は、どちらも送信されたメッセージの件数です。 |
| sms-inbound | ショート コードとロング コードの両方への、すべての 着信 SMS メッセージです。 |
| sms-inbound-longcode | ロング コード宛の、すべての着信 SMS メッセージです。 |
| sms-inbound-shortcode | ショート コード宛の、すべての着信 SMS メッセージです。 |
| sms-outbound | ショート コードとロング コードの両方からの、すべての発信 SMS メッセージです。 |
| sms-outbound-longcode | ロング コードからの、すべての発信 SMS メッセージです。 |
| sms-outbound-shortcode | ショート コードからの、すべての発信 SMS メッセージです。 |
| sms-messages-carrierfees | All carrier fees for SMS messages. |
| MMS | 着信と発信の、すべての MMS メッセージです。Count と Usage は、どちらも送信されたメッセージの件数です。 |
| mms-inbound | ショートコードとロングコードの両方への、すべての着信 MMS メッセージです。 |
| mms-inbound-longcode | ロングコード宛の、すべての着信 MMS メッセージです。 |
| mms-inbound-shortcode | ショートコード宛の、すべての着信 MMS メッセージです。 |
| mms-outbound | ショートコードとロングコードの両方からの、すべての発信 MMS メッセージです。 |
| mms-outbound-longcode | ロングコードからの、すべての発信 MMS メッセージです。 |
| mms-outbound-shortcode | ショートコードからの、すべての発信 MMS メッセージです。 |
| mms-messages-carrierfees | All carrier fees for MMS messages. |
| mediastorage | このアカウントで保存されたメディアが使用する保存容量です。Count は保存されたメディアファイルの件数、Usage はメガバイト数、Price はメディアの保存料金です。 |
WhatsApp Business API
| Category | 概要 |
|---|---|
| channels-whatsapp-outbound | WhatsApp Template Message - WhatsApp charges a per message fee to send Template messages. This price depends on the destination country. See our pricing page for details. |
| channels-whatsapp-inbound | WhatsApp does not charge for inbound messages. This cost will always be zero. |
| channels-messaging-inbound | Twilio charges a flat-rate per inbound message platform fee for any and all countries. |
| channels-messaging-outbound | Twilio charges a flat-rate per outbound message platform fee for any and all countries. |
Twilio Conversations
| Category | 概要 |
|---|---|
| pchat-users | Active Monthly Users - An active user is defined as someone who creates a user or conversation, or edits, or is assigned to a conversation. This includes reading conversations, sending messages in a chat view, or sending and receiving SMS and WhatsApp messages via the Conversations product. |
| pchat-conv-med-storage | Media Storage - Photos, videos, or other files stored and distributed in Conversations are billed at a monthly rate according to their size, prorated daily. Only stored media (pictures, videos, etc.) incurs a charge; ordinary text-only message bodies are stored at no cost. |
電話番号
| Category | 概要 |
|---|---|
| phonenumbers | このアカウントが所有するすべての電話番号です。携帯電話番号、無料電話番号、および国内電話番号があります。 |
| phonenumbers-local | このアカウントが所有するすべての国内電話番号です。 |
| phonenumbers-mobile | このアカウントが所有するすべての携帯電話番号です。 |
| phonenumbers-tollfree | このアカウントが所有するすべての無料電話番号です。 |
| phonenumbers-cps | すべての電話番号秒間通話回数（CPS）増加分です。 |
| phonenumbers-setups | すべての電話番号設定料金です。 |
| shortcodes | このアカウントが所有する、すべての種別のショート コードです。 |
| shortcodes-customerowned | このアカウントが所有する、すべての他のプロバイダーから貸与されたショート コードです。 |
| shortcodes-mms-enablement | すべてのショートコード MMS 有効化料金です。 |
| shortcodes-mps | すべてのショートコード秒間メッセージ数（MPS）増加分です。 |
| shortcodes-random | このアカウントが所有する、すべてのランダムに割り当てられたショート コードです。 |
| shortcodes-uk | このアカウントが所有する、すべての英国ショートコードです。 |
| shortcodes-vanity | このアカウントが所有する、すべてのカスタム ショート コードです。 |
ルックアップ
| Category | 概要 |
|---|---|
| lookups | すべてのルックアップです。キャリア、発信者 ID、および番号形式のルックアップが含まれます。 |
| carrier-lookups | すべてのキャリアルックアップです。 |
| calleridlookups | すべての callerID （CallerName）ルックアップです。 |
| number-format-lookups | すべての番号形式ルックアップです。 |
Elastic SIP Trunking
| Category | 概要 |
|---|---|
| trunking-origination | 携帯電話番号、無料電話番号、および国内電話番号へのすべてのトランキングオリジネーション（着信）通話です。 |
| trunking-origination-local | 国内電話番号へのすべてのトランキングオリジネーション（着信）通話です。 |
| trunking-origination-mobile | 携帯電話番号へのすべてのトランキングオリジネーション（着信）通話です。 |
| trunking-origination-tollfree | 無料電話番号へのすべてのトランキングオリジネーション（着信）通話です。 |
| trunking-termination | すべてのトランキングターミネーション（発信）通話です。 |
| trunking-recordings | トランク通話の録音です。Count は録音件数、Usage は録音分数です。 |
| trunking-cps | すべてのトランキング秒間通話回数（CPS）増加分です。 |
| trunking-secure | すべての保護されたトランク通話です。 |
| voice-insights-sip-trunking-insights-on-demand-minute | Voice Insights Advanced Features for trunking calls |
Sync
| Category | 概要 |
|---|---|
| sync-actions | All incoming requests from your application that read and write data. It means actions include any read or write from an SDK or the REST API. Resulting webhooks, updates to connected endpoints, and storage are included in the cost of an action. |
| sync-endpoint-hours | An endpoint-hour is counted once per wall-clock hour for each unique device connected to Sync. Endpoints can be unique devices or browser tabs. Each unique endpoint will incur charges for at most four hours of every calendar day; the remainder are free of charge. |
| sync-endpoint-hours-above-daily-cap | All hours spent above four hours limit are shown separately. All these hours are free of charge. |
TaskRouter
| Category | 概要 |
|---|---|
| taskrouter-tasks | TaskRouterで作成されたすべてのタスクです。 |
Programmable Video
| Category | 概要 |
|---|---|
| pv | All Programmable Video usage including TURN. Price accounts for expenses in all Programmable Video products. Count and Usage should be ignored. |
| group-rooms | Accounts for all Group Rooms usage. Count is the number of rooms. Usage should be ignored. |
| group-rooms-participant-minutes | All participant usage in Group Rooms. Count and Usage measure the number of participant minutes. |
| group-rooms-data-track | All Group Room Data Tracks activity. Count and Usage measure thousands of messages sent. |
| small-group-rooms | Accounts for all Small Group Rooms usage. Count is the number of rooms. Usage should be ignored. |
| small-group-rooms-participant-minutes | All participant usage in Small Group Rooms. Count and Usage measure the number of participant minutes. |
| small-group-rooms-data-track | All Small Group Room Data Tracks activity. Count and Usage measure thousands of messages sent. |
| pv-rooms | Accounts for all Peer-to-Peer Rooms usage. Count is the number of rooms. Usage is the number of participant minutes. |
| peer-to-peer-rooms-participant-minutes | All participant usage in P2P Rooms. Count and Usage measure the number of participant minutes. |
| video-recordings | All usage regarding video Recordings and Compositions. Count and Usage should be ignored. |
| group-rooms-recorded-minutes | All Recordings generated out of Group Rooms (including Small Group Rooms). Count and Usage measure the number of recorded participant minutes. |
| pv-composition-minutes | All Video Recording Compositions. Count and Usage measure the number of composition minutes. |
| group-rooms-encrypted-media-recorded | All encrypted media including Group Room Recordings and Compositions. Count and Usage measure the number of encrypted participant minutes and composition minutes. |
| group-rooms-media-stored | All media stored in Twilio by Programmable Video Services including Recordings and Compositions. Count and Usage measure the number of stored GB/day (Gigabytes per day). |
| group-rooms-media-downloaded | All media downloaded from Twilio regarding Programmable Video Services. This includes Recordings and Compositions. Count and Usage measure the number of downloaded GB (Gigabytes). |
| turnmegabytes | All TURN data relayed by Twilio. Count and Usage measure the relayed traffic in MB (Megabytes) |
| turnmegabytes-australia | TURN data relayed by Twilio in the Australia AWS region. Count and Usage measure the relayed traffic in MB (Megabytes) |
| turnmegabytes-brasil | TURN data relayed by Twilio in the Brazil AWS region. Count and Usage measure the relayed traffic in MB (Megabytes) |
| turnmegabytes-india | TURN data relayed by Twilio in the India AWS region. Count and Usage measure the relayed traffic in MB (Megabytes) |
| turnmegabytes-ireland | TURN data relayed by Twilio in the Ireland AWS region. Count and Usage measure the relayed traffic in MB (Megabytes) |
| turnmegabytes-japan | TURN data relayed by Twilio in the Japan AWS region. Count and Usage measure the relayed traffic in MB (Megabytes) |
| turnmegabytes-singapore | TURN data relayed by Twilio in the Singapore AWS region. Count and Usage measure the relayed traffic in MB (Megabytes) |
| turnmegabytes-useast | TURN data relayed by Twilio in the US (East) AWS region. Count and Usage measure the relayed traffic in MB (Megabytes) |
| turnmegabytes-uswest | TURN data relayed by Twilio in the US (West) AWS region. Count and Usage measure the relayed traffic in MB (Megabytes) |
| turnmegabytes-germany | TURN data relayed by Twilio in the Germany AWS region. Count and Usage measure the relayed traffic in MB (Megabytes) |
Programmable Chat
| Category | 概要 |
|---|---|
| pchat-users | Active Monthly Users - An active user is defined as someone who creates a user or conversation, or edits, or is assigned to a chat channel. This includes reading conversations or sending messages. |
| pchat-conv-med-storage | Media Storage - Photos, videos, or other files stored and distributed in chat channels are billed at a monthly rate according to their size, prorated daily. Only stored media (pictures, videos, etc.) incurs a charge; ordinary text-only message bodies are stored at no cost. |
確認
| Category | 概要 |
|---|---|
| verify-push | All Verify push verifications. Each verification is defined as a challenge that is updated with a status of approved or denied. |
| authy-phone-verifications | All Verify SMS and Voice verifications. |
| authy-verify-email-verifications | All Verify email verifications. |
| authy-verify-outbound-email | All Verify one-time tokens requested to be delivered via email. |
authy
| Category | 概要 |
|---|---|
| authy-authentications | すべての Authy 認証です。 |
| authy-calls-outbound | すべての Authy 発信通話です。この利用状況は音声カテゴリーにも含まれます。 |
| authy-monthly-fees | すべての Authy 月額料金です。 |
| authy-phone-intelligence | すべての Authy 電話インテリジェンスリクエストです。 |
| authy-sms-outbound | すべての Authy 発信 SMS メッセージです。この利用状況は SMS カテゴリーにも含まれるので、注意してください。 |
| authy-outbound-email | All Authy one-time tokens requested to be delivered via email. |
Studio
| Category | 概要 |
|---|---|
| studio-engagements | すべてのStudio Engagementです |
モニター
| Category | 概要 |
|---|---|
| monitor-reads | すべてのモニターイベント API 読み込みです。 |
| monitor-writes | すべてのモニターイベント書き込みです。 |
| monitor-storage | すべてのモニターイベント保存料金です。 |
Internet of Things
| Category | 概要 |
|---|---|
| wireless-orders-starter | All Programmable Wireless Starter Packs ordered. |
| wireless-orders-bulk | All Programmable Wireless Bulk SIMs ordered. |
| wireless-mrc-payg | All Programmable Wireless Monthly Fees for SIMs using PAYG data metering. |
| supersim-subscription-fees-payg | All Super SIM subscription fees for SIMs using PAYG data metering. |
| supersim-data-payg-northamerica-usa | All Super SIM data usage from SIMs using PAYG data metering in the United States. |
| supersim-commands-europe-germany | All Super SIM commands sent to or from SIMs in Germany. |
Autopilot
| Category | 概要 |
|---|---|
| autopilot-messaging | All Autopilot messages. Includes messages coming from Programmable Messaging, Programmable Chat and custom channels. |
| autopilot-voice | All Autopilot voice minutes. Count is the number of minutes. |
| autopilot-other | All Autopilot API Queries. Count is the number of queries. |
| autopilot-home-assistants | All messages from Alexa or Google Assistant. |
その他
| Category | 概要 |
|---|---|
| premiumsupport | すべてのプレミアムサポート料金です。 |
| totalprice | すべての利用の合計料金です。Usage は Price と同じになります。Count は空になります。 Twilio の利用料金にはどの利用カテゴリーにも当てはまらないものがあり、すべての UsageRecord の Price の合計が TotalPrice の Price と一致する場合としない場合がありますので、注意してください。 |
UsageRecord インスタンス リソース
UsageRecord リソースに直接リクエストを発行することはできません。 UsageRecords リスト リソース または サブリソースのいずれかに、リクエストを発行してください。
ヘルプが必要ですか？
誰しもが一度は考える「コーディングって難しい」。そんな時は、お問い合わせフォームから質問してください。 または、Stack Overflow でTwilioタグのついた情報から欲しいものを探してみましょう。