{"openapi":"3.1.0","info":{"title":"Twilio Usage (BYOK) API","version":"0.1.0","description":"Twilio Usage (BYOK) lets an AI assistant read your own Twilio Usage data through the Twilio Usage API with a key you supply (Account SID or API key SID (use a restricted API key, SID starts with SK, rather than the main Auth Token where possible)). Read-only: 10 tools (get_balance, list_usage_today, list_usage_yesterday, list_usage_this_month, list_usage_last_month, list_usage_daily,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-twilio-usage.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-twilio-usage/docs"},"termsOfService":"https://connectorbay.com/byok-twilio-usage/terms"},"servers":[{"url":"https://byok-twilio-usage.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-twilio-usage/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_balance":{"post":{"operationId":"get_balance","summary":"Show the account balance with currency. Use for \"How much Twilio balance do I have left\".","description":"Show the account balance with currency. Use for \"How much Twilio balance do I have left\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_sid":{"description":"The Twilio Account SID: 'AC' followed by 32 hex characters (shown on the Twilio console home page).","maxLength":34,"title":"Account Sid","type":"string"}},"required":["account_sid"],"title":"get_balanceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_usage_today":{"post":{"operationId":"list_usage_today","summary":"List usage and spend per category for today, with count, usage, price and unit. Only reads; nothing is billed for the re","description":"List usage and spend per category for today, with count, usage, price and unit. Only reads; nothing is billed for the read. Use for \"How much did my Twilio account spend today\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_sid":{"description":"The Twilio Account SID: 'AC' followed by 32 hex characters (shown on the Twilio console home page).","maxLength":34,"title":"Account Sid","type":"string"},"category":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only this usage category, for example sms, calls, phonenumbers or totalprice (Twilio's usage category names).","title":"Category"},"start_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only usage on or after this date (YYYY-MM-DD, GMT).","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only usage on or before this date (YYYY-MM-DD, GMT).","title":"End Date"},"include_subaccounts":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True (default) to include usage of subaccounts, false for only the main account.","title":"Include Subaccounts"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return (1 to 1000).","title":"Page Size"},"page_token":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: take the PageToken value from next_page_uri in the previous answer (leave empty for the first page).","title":"Page Token"}},"required":["account_sid"],"title":"list_usage_todayArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_usage_yesterday":{"post":{"operationId":"list_usage_yesterday","summary":"List usage and spend per category for yesterday, with count, usage, price and unit. Only reads; nothing is billed for th","description":"List usage and spend per category for yesterday, with count, usage, price and unit. Only reads; nothing is billed for the read. Use for \"What was my Twilio usage yesterday\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_sid":{"description":"The Twilio Account SID: 'AC' followed by 32 hex characters (shown on the Twilio console home page).","maxLength":34,"title":"Account Sid","type":"string"},"category":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only this usage category, for example sms, calls, phonenumbers or totalprice (Twilio's usage category names).","title":"Category"},"start_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only usage on or after this date (YYYY-MM-DD, GMT).","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only usage on or before this date (YYYY-MM-DD, GMT).","title":"End Date"},"include_subaccounts":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True (default) to include usage of subaccounts, false for only the main account.","title":"Include Subaccounts"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return (1 to 1000).","title":"Page Size"},"page_token":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: take the PageToken value from next_page_uri in the previous answer (leave empty for the first page).","title":"Page Token"}},"required":["account_sid"],"title":"list_usage_yesterdayArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_usage_this_month":{"post":{"operationId":"list_usage_this_month","summary":"List usage and spend per category for the current month so far, with count, usage, price and unit. Only reads; nothing i","description":"List usage and spend per category for the current month so far, with count, usage, price and unit. Only reads; nothing is billed for the read. Use for \"What is my Twilio spend this month by category\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_sid":{"description":"The Twilio Account SID: 'AC' followed by 32 hex characters (shown on the Twilio console home page).","maxLength":34,"title":"Account Sid","type":"string"},"category":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only this usage category, for example sms, calls, phonenumbers or totalprice (Twilio's usage category names).","title":"Category"},"start_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only usage on or after this date (YYYY-MM-DD, GMT).","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only usage on or before this date (YYYY-MM-DD, GMT).","title":"End Date"},"include_subaccounts":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True (default) to include usage of subaccounts, false for only the main account.","title":"Include Subaccounts"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return (1 to 1000).","title":"Page Size"},"page_token":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: take the PageToken value from next_page_uri in the previous answer (leave empty for the first page).","title":"Page Token"}},"required":["account_sid"],"title":"list_usage_this_monthArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_usage_last_month":{"post":{"operationId":"list_usage_last_month","summary":"List usage and spend per category for the previous month, with count, usage, price and unit. Only reads; nothing is bill","description":"List usage and spend per category for the previous month, with count, usage, price and unit. Only reads; nothing is billed for the read. Use for \"How much did Twilio cost me last month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_sid":{"description":"The Twilio Account SID: 'AC' followed by 32 hex characters (shown on the Twilio console home page).","maxLength":34,"title":"Account Sid","type":"string"},"category":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only this usage category, for example sms, calls, phonenumbers or totalprice (Twilio's usage category names).","title":"Category"},"start_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only usage on or after this date (YYYY-MM-DD, GMT).","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only usage on or before this date (YYYY-MM-DD, GMT).","title":"End Date"},"include_subaccounts":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True (default) to include usage of subaccounts, false for only the main account.","title":"Include Subaccounts"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return (1 to 1000).","title":"Page Size"},"page_token":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: take the PageToken value from next_page_uri in the previous answer (leave empty for the first page).","title":"Page Token"}},"required":["account_sid"],"title":"list_usage_last_monthArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_usage_daily":{"post":{"operationId":"list_usage_daily","summary":"List usage and spend per category for each day in the chosen date range, with count, usage, price and unit. Only reads; ","description":"List usage and spend per category for each day in the chosen date range, with count, usage, price and unit. Only reads; nothing is billed for the read. Use for \"Show my Twilio usage per day last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_sid":{"description":"The Twilio Account SID: 'AC' followed by 32 hex characters (shown on the Twilio console home page).","maxLength":34,"title":"Account Sid","type":"string"},"category":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only this usage category, for example sms, calls, phonenumbers or totalprice (Twilio's usage category names).","title":"Category"},"start_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only usage on or after this date (YYYY-MM-DD, GMT).","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only usage on or before this date (YYYY-MM-DD, GMT).","title":"End Date"},"include_subaccounts":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True (default) to include usage of subaccounts, false for only the main account.","title":"Include Subaccounts"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return (1 to 1000).","title":"Page Size"},"page_token":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: take the PageToken value from next_page_uri in the previous answer (leave empty for the first page).","title":"Page Token"}},"required":["account_sid"],"title":"list_usage_dailyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_usage_monthly":{"post":{"operationId":"list_usage_monthly","summary":"List usage and spend per category for each month in the chosen date range, with count, usage, price and unit. Only reads","description":"List usage and spend per category for each month in the chosen date range, with count, usage, price and unit. Only reads; nothing is billed for the read. Use for \"Show my Twilio usage per month this year\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_sid":{"description":"The Twilio Account SID: 'AC' followed by 32 hex characters (shown on the Twilio console home page).","maxLength":34,"title":"Account Sid","type":"string"},"category":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only this usage category, for example sms, calls, phonenumbers or totalprice (Twilio's usage category names).","title":"Category"},"start_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only usage on or after this date (YYYY-MM-DD, GMT).","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only usage on or before this date (YYYY-MM-DD, GMT).","title":"End Date"},"include_subaccounts":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True (default) to include usage of subaccounts, false for only the main account.","title":"Include Subaccounts"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return (1 to 1000).","title":"Page Size"},"page_token":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: take the PageToken value from next_page_uri in the previous answer (leave empty for the first page).","title":"Page Token"}},"required":["account_sid"],"title":"list_usage_monthlyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_usage_all_time":{"post":{"operationId":"list_usage_all_time","summary":"List usage and spend per category for the whole life of the account, with count, usage, price and unit. Only reads; noth","description":"List usage and spend per category for the whole life of the account, with count, usage, price and unit. Only reads; nothing is billed for the read. Use for \"What is my all-time Twilio usage per category\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_sid":{"description":"The Twilio Account SID: 'AC' followed by 32 hex characters (shown on the Twilio console home page).","maxLength":34,"title":"Account Sid","type":"string"},"category":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only this usage category, for example sms, calls, phonenumbers or totalprice (Twilio's usage category names).","title":"Category"},"start_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only usage on or after this date (YYYY-MM-DD, GMT).","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Only usage on or before this date (YYYY-MM-DD, GMT).","title":"End Date"},"include_subaccounts":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True (default) to include usage of subaccounts, false for only the main account.","title":"Include Subaccounts"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return (1 to 1000).","title":"Page Size"},"page_token":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: take the PageToken value from next_page_uri in the previous answer (leave empty for the first page).","title":"Page Token"}},"required":["account_sid"],"title":"list_usage_all_timeArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_usage_triggers":{"post":{"operationId":"list_usage_triggers","summary":"List usage triggers (alerts fired when usage or spend crosses a value) with current value and last fired time. Callback ","description":"List usage triggers (alerts fired when usage or spend crosses a value) with current value and last fired time. Callback URLs are not returned. Use for \"Which Twilio spend alerts have I set up\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_sid":{"description":"The Twilio Account SID: 'AC' followed by 32 hex characters (shown on the Twilio console home page).","maxLength":34,"title":"Account Sid","type":"string"},"recurring":{"anyOf":[{"enum":["daily","monthly","yearly","alltime"],"type":"string"},{"type":"null"}],"default":null,"description":"Only triggers that recur daily, monthly, yearly or never (alltime).","title":"Recurring"},"trigger_by":{"anyOf":[{"enum":["count","usage","price"],"type":"string"},{"type":"null"}],"default":null,"description":"Only triggers that watch count, usage or price.","title":"Trigger By"},"usage_category":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only triggers on this usage category.","title":"Usage Category"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return (1 to 1000).","title":"Page Size"},"page_token":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: take the PageToken value from next_page_uri in the previous answer (leave empty for the first page).","title":"Page Token"}},"required":["account_sid"],"title":"list_usage_triggersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_usage_trigger":{"post":{"operationId":"get_usage_trigger","summary":"Get one usage trigger: category, threshold, current value, recurrence and last fired time. Use for \"Has usage trigger UT","description":"Get one usage trigger: category, threshold, current value, recurrence and last fired time. Use for \"Has usage trigger UT... fired\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"account_sid":{"description":"The Twilio Account SID: 'AC' followed by 32 hex characters (shown on the Twilio console home page).","maxLength":34,"title":"Account Sid","type":"string"},"sid":{"description":"The SID of the usage trigger: 'UT' followed by 32 hex characters.","maxLength":34,"title":"Sid","type":"string"}},"required":["account_sid","sid"],"title":"get_usage_triggerArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}