Request Smart Meter Texas Data

experimental

Pull up to 12 months of 15-minute electricity usage for a Texas smart meter from Smart Meter Texas: grid imports, solar exports, monthly totals, peak demand, and download files for CSV, Aurora Solar, OpenSolar, and Solargraf. For a Texas homeowner pulling their own meter's usage, or an installer pulling a customer's. Needs the ESI ID (or service address), meter number, and current electricity provider, all printed on the electricity bill. If the user has shared a bill image or PDF, read those values from it and call this tool; it takes the values, not the file.

Starts a Smart Meter Texas pull for one meter and waits up to `waitSeconds` (default 20) for the data. Most pulls finish in about 20 seconds; when one takes longer the result is `pending` with a `requestId`, and `get_smt_data` returns the data once it's ready. **What you need from the bill** - ESI ID (17 or 22 digits), or the service address so it can be looked up - Meter number (8 to 12 characters, not the serial printed on the meter) - Current electricity provider, as named on the bill **What you get back** - Monthly grid imports, solar exports, net usage, and peak demand - Average monthly import and export, and whether the meter exports solar - Download links for CSV, Aurora Solar, OpenSolar, and Solargraf files **How it works**: this creates a Smart Meter Texas data-sharing agreement for the meter, the same flow as [meterplan.com/smart-meter-texas](https://meterplan.com/smart-meter-texas). Only request data for a meter you're authorized to access: your own, or a customer's with their permission. A pull completed for the same meter in the last 24 hours is reused instead of creating a new agreement, and a pull already in progress is joined rather than duplicated. **Scope**: residential and small-business meters in the deregulated Texas market that report to Smart Meter Texas. Not for municipal utilities or co-ops (for example Austin Energy or CPS Energy), and not for reading bill PDFs.

Endpoint

POST https://meterplan.com/api/v1/request-smt-data

MCP tool name: request_smt_data

Inputs

esiIdstring
ESI ID (Electric Service Identifier) of the meter: a 17 or 22 digit number printed on the electricity bill, usually labeled "ESI ID" or "ESIID" near the service address. Spaces and dashes are fine. Provide this or address.
addressstring
Service address of the home (street, city, and ZIP), used to look up the ESI ID when it isn't handy. Provide this or esiId; esiId is more reliable.
meterNumberstringrequired
Meter number printed on the electricity bill, usually in the meter-read or usage section: 8 to 12 letters and digits, sometimes ending in "LG". This is not the serial number printed on the meter itself.
currentRetaileranyrequired
The current electricity provider named on the bill, chosen from the listed provider names (for example "TXU Energy", "Reliant Energy", or "Gexa Energy"), or its 5-digit PUCT certificate number. If the user's provider isn't on the list, ask them for the name exactly as printed on the bill. Smart Meter Texas checks it against the meter, so it must be the provider today, not a past one.
waitSecondsnumber
How long to wait for Smart Meter Texas before returning, 0 to 45 seconds (default 20). Most pulls finish in about 20 seconds; if time runs out the result is pending with a requestId to pass to get_smt_data.

Outputs

statusenum<needs_clarification | pending | complete | error>
needs_clarification: the address matched more than one meter and nothing was started; ask the user which of candidates is theirs, then call request_smt_data with that esiId. pending: Smart Meter Texas is still working; call get_smt_data with requestId after checkAfterSeconds. complete: usage data is included. error: see errorMessage.
requestIdstring
Identifier for this pull. Pass it to get_smt_data. Null only when status is needs_clarification.
reusedboolean
True when this result comes from a pull for the same meter in the last 24 hours (or one already in progress) instead of a new Smart Meter Texas request.
stepstring
Current processing step, in plain words.
checkAfterSecondsnumber
Present when status is pending: wait about this long before calling get_smt_data.
esiIdstring
ESI ID of the meter.
utilitystring
Utility (TDU) that serves the meter, such as Oncor or CenterPoint, when known.
serviceAddressstring
Service address on file for this pull, when known.
dataStartstring
First reading, local Central Time (YYYY-MM-DDTHH:MM:00).
dataEndstring
Last reading, local Central Time (YYYY-MM-DDTHH:MM:00).
readingCountnumber
Number of 15-minute readings covered.
monthlyAggregatesarray<object>
Per-month totals, oldest first.
avgMonthlyImportKwhnumber
Average grid import per month, in kWh.
avgMonthlyExportKwhnumber
Average grid export (solar sent back) per month, in kWh.
peakDemandKwnumber
Highest 15-minute grid import across the data, in kW.
hasSolarExportsboolean
True when the meter recorded any exports to the grid.
intervalsarray<object>
Raw 15-minute readings, oldest first. Only when includeIntervals is true; capped at the most recent 3,000.
intervalsTruncatedboolean
True when intervals were capped at 3,000. Use the download links for the full year.
exportsobject
Download links for the full data in each format. Present when status is complete.
errorCodestring
Machine-readable failure reason when status is error, such as smt_agreement_failed or no_data.
errorMessagestring
What went wrong and what to do next, when status is error.
candidatesarray<object>
Present when status is needs_clarification: the meters found at the given address. Show them to the user and let them choose; never pick one for them.
summarystring
One-paragraph plain-language summary of the result.

Example prompts

“Pull my home's smart meter data. My ESI ID is 10443720012345678, meter 119026839, and I'm with TXU Energy.”
“Here's my electricity bill. Can you pull my actual usage and show me how much solar I'm sending back?”
“Pull 12 months of interval data for this customer and give me the Aurora file.”
“How much solar did my house export to the grid each month this year?”
“Get 15-minute usage for 123 Main St, Dallas, TX 75201, meter 119026839, Reliant Energy.”