Twilio API for AI agents: what an SMS, a call and a lookup really cost

Agents that book appointments, chase invoices or confirm deliveries eventually need to reach a phone. Twilio covers the three jobs that come up most: sending an SMS, placing a voice call, and checking whether a number is real before you spend money on it. The thing most people learn the expensive way: a 161-character reminder costs twice as much as a 160-character one, and a message that fails is not free either. This guide gives you the numbers, the fields that come back, and the mistakes an agent makes that a person would not.

Why this matters for agents

A person sends one text and reads the reply. An agent sends ten thousand, never reads the bill, and retries whenever something looks wrong. Three properties of Twilio shape how that goes.

First, you are billed on segments, not messages. Twilio charges $0.0083 per outbound SMS segment in the US as of October 2026. A body of up to 160 GSM-7 characters is one segment; once it goes over, each segment carries only 153 characters because 7 are used for the reassembly header. A single curly quote or emoji switches the whole message to UCS-2, where a segment holds 70 characters, or 67 when split. Language models love curly quotes. Check num_segments on every response, and strip non-GSM characters before sending.

Second, the first response tells you almost nothing. A successful POST returns status: "queued". Delivery, failure and price all arrive later, through a StatusCallback or by fetching the message again. An agent that reads queued as "done" will report success on messages that never arrived.

Third, there is no idempotency key on the Messages endpoint. If your HTTP call times out after Twilio accepted it, the text has gone out. A blind retry sends it twice, and the customer gets two reminders. Before retrying, list recent messages for that To number and the last few minutes, and only resend if nothing is there.

What to check before spending: that the number is valid (free), that it is a mobile line ($0.008), that you are sending inside the ValidityPeriod window you intend, and that the body is one segment. Each check is cheaper than the mistake it prevents.

What Twilio returns

Sending an SMS creates a Message resource. The fields an agent cares about:

• sid: the message ID, starting with SM or MM
• status: queued, sending, sent, delivered, undelivered or failed; accepted and scheduled appear only with a Messaging Service
• num_segments: what you are billed on; it starts at 0 on Messaging Service sends until a sender is assigned
• price and price_unit: populated after the message is sent, so usually null on the first response
• error_code and error_message: set when the status is failed or undelivered, null otherwise

The body limit is 1,600 characters, which is up to 11 segments at 153 each. ValidityPeriod defaults to 36,000 seconds (10 hours): a message still sitting in Twilio's queue after that is dropped, which is rarely what you want for a "your table is ready" text. Set it to a few minutes for time-sensitive sends.

Placing a call creates a Call resource with a sid starting with CA, a status (queued, ringing, in-progress, completed, busy, failed, no-answer or canceled) and a duration in seconds once the call ends. What the call says comes from TwiML, passed inline as Twiml or fetched from a Url. If you turn on MachineDetection=Enable, AnsweredBy comes back as human, machine_start, fax or unknown; with DetectMessageEnd you also get machine_end_beep, machine_end_silence and machine_end_other. There is no plain machine value, so match on the prefix.

Looking up a number with Lookup v2 returns valid, phone_number in E.164, national_format, country_code and calling_country_code, plus validation_errors when it fails. Add Fields=line_type_intelligence or Fields=caller_name for the paid packages. The paid fields are nested objects, and each can be null when Twilio has no data, so a lookup can succeed and still not answer your question.

The economics

Twilio's US list prices, as of October 2026, from its SMS, Voice and Lookup pricing pages:

Three multipliers matter. Segments multiply the base rate and the carrier fee. Carrier fees are added on top of the $0.0083 and depend on the recipient's network, so you cannot know the exact cost of a text before you send it. And voice minutes are rounded up: a 61-second call bills as 2 minutes, so a 30-second confirmation call costs the same $0.014 as a 59-second one.

Telnyx lists $0.004 per long-code SMS plus carrier fee and Plivo $0.0077, as of October 2026. The carrier fees are nearly identical across all three (AT&T $0.0035, T-Mobile $0.0045), which is why the gap narrows once you add them.

Worked example: appointment reminders at three volumes, sent to T-Mobile customers for a round number.

• One segment (160 GSM-7 characters or fewer): $0.0083 + $0.0045 = $0.0128 each. 100 reminders cost $1.28, 1,000 cost $12.80, 10,000 cost $128.
• Two segments (a 180-character body, or a 160-character one with an emoji): everything doubles. 10,000 reminders cost $256.
• Add a line-type lookup first: 10,000 × $0.008 = $80 extra, once per number rather than per message.

A 2-minute confirmation call to each of those 10,000 customers is 10,000 × 2 × $0.014 = $280, plus $75 if you enable answering machine detection. Calls that end failed or busy are not billed for minutes.

Through AMXP, inspect shows the per-call price before the agent runs anything, and it is charged to your prepaid balance.

How to call it from your agent

AMXP is in private preview, so this is how it works through AMXP once it opens. The agent finds the Twilio tool, reads its spec, then runs it with the same field names Twilio uses:

const [tool] = await amxp.discover({ query: "send an SMS", provider: "twilio" })
const spec = await amxp.inspect(tool.id) // params, price per call, examples

// 1. Free validation first, paid line type only if the number is new to you
const check = await amxp.execute(lookupTool.id, {
  PhoneNumber: "+14155550123",
  Fields: "line_type_intelligence",
})
if (!check.output.valid || check.output.line_type_intelligence?.type !== "mobile") return

// 2. Send one segment, with a short validity window and a status webhook
const run = await amxp.execute(tool.id, {
  To: "+14155550123",
  From: "+14155550100",
  Body: "Reminder: your appointment is tomorrow at 10:00. Reply C to confirm.", // 68 chars, GSM-7
  ValidityPeriod: 600,
  StatusCallback: "https://example.com/hooks/sms-status",
})
// run.output.status === "queued"; run.output.num_segments === "1"
// delivered / undelivered / failed arrives at the StatusCallback later

For comparison, the direct call is a form-encoded POST to https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Messages.json with To, From (or MessagingServiceSid) and Body, authenticated with your Account SID and auth token. Lookup is a GET to https://lookups.twilio.com/v2/PhoneNumbers/{number}?Fields=line_type_intelligence.

What most people get wrong

Treating queued as delivered. The create response is an acknowledgement, not a receipt. Store the sid, and let the StatusCallback or a later fetch update the record. Report success to the user only on delivered, or on sent when the carrier does not return receipts.

Letting the model write the body. A model-written reminder with a curly apostrophe and an emoji is UCS-2, which halves the segment size to 70 characters. Normalise quotes, ban emoji, and assert num_segments === "1" in the response. If it is not, log it, because the cost of that template just doubled.

Sending to numbers nobody validated. An invalid To returns error 21211 and the request fails. A valid but filtered message ends undelivered with error 30007, and Twilio still charges a $0.001 processing fee for each message that ends failed. Validation is free. Use it.

Retrying on timeout. There is no idempotency key. A retry after a network timeout is a second message. List recent messages to the same To before resending.

Forgetting MachineDetection on outbound calls. Without it, your TwiML plays into voicemail and you pay for the minutes. With MachineDetection=Enable, AnsweredBy tells you machine_start and you can hang up or leave a shorter message. It costs $0.0075 per call and adds a short pause before the first word, so set AsyncAmd=true if you would rather start talking and adjust mid-call.

When to use something else

• You send from a fixed brand number at volume. A sender costs $1.15 per month for a US long code, and registered 10DLC campaigns or short codes are account-level setup. If messaging is core to your product, your own Twilio account wins. AMXP is for the gaps: occasional sends, prototypes, and agents that should not hold carrier credentials.
• Price per segment matters more than the ecosystem. Telnyx is about half Twilio's base rate on US long codes and Plivo is slightly cheaper; Sinch is worth a quote outside the US.
• The agent should talk, not just dial. Twilio places the call; something else has to listen and respond. Vapi, Retell AI and Bland AI run the conversation, and Saperly handles phone calls for agents.
• You only need email. AgentMail gives agents their own inboxes, and Resend sends transactional mail.

Common questions

Can an AI agent send SMS without a Twilio account?

Once AMXP opens, an agent will be able to call Twilio's messaging tool from its AMXP balance without its own Twilio credentials. Today you need your own Twilio account and a sending number.

Why is price empty in the response?

Twilio fills in price after the message is sent, so it is null in the first response. Fetch the message again later, or read it from the StatusCallback payload once the status is final.

How do I check whether a number is a mobile before texting it?

Use Lookup v2 with Fields=line_type_intelligence. It costs $0.008 per request as of October 2026, while basic validation alone is free. Cache the answer per number; line types rarely change.