MEmeterplan
bill-analysis

Request Smart Meter Texas Data

Changed on

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 a CSV download of the full 15-minute data (Aurora Solar, OpenSolar, and Solargraf import files are available for installers who ask). 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
  • A CSV download of the full 15-minute data, plus Aurora Solar, OpenSolar, and Solargraf import files on request

How it works: this creates a Smart Meter Texas data-sharing agreement for the meter, the same flow as 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.

post/api/v1/request-smt-data

Request

Request body

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.

meterNumberstring required

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.

waitSecondsinteger

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.

Response

Tool ran successfully.

status'needs_clarification' | 'pending' | 'complete' | 'error' required

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 nullable required

Identifier for this pull. Pass it to get_smt_data. Null only when status is needs_clarification.

reusedboolean required

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 required

Current processing step, in plain words.

checkAfterSecondsnumber

Present when status is pending: wait about this long before calling get_smt_data.

esiIdstring nullable required

ESI ID of the meter.

utilitystring nullable required

Utility (TDU) that serves the meter, such as Oncor or CenterPoint, when known.

serviceAddressstring nullable required

Service address on file for this pull, when known.

dataStartstring nullable required

First reading, local Central Time (YYYY-MM-DDTHH:MM:00).

dataEndstring nullable required

Last reading, local Central Time (YYYY-MM-DDTHH:MM:00).

readingCountnumber required

Number of 15-minute readings covered.

avgMonthlyImportKwhnumber nullable required

Average grid import per month, in kWh.

avgMonthlyExportKwhnumber nullable required

Average grid export (solar sent back) per month, in kWh.

peakDemandKwnumber nullable required

Highest 15-minute grid import across the data, in kW.

hasSolarExportsboolean nullable required

True when the meter recorded any exports to the grid.

intervalsTruncatedboolean

True when intervals were capped at 3,000. Use the download links for the full year.

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.

summarystring required

One-paragraph plain-language summary of the result.

Changes