--- title: "Request Smart Meter Texas Data" method: POST path: "/api/v1/request-smt-data" tags: ["bill-analysis"] --- # Request Smart Meter Texas Data `POST /api/v1/request-smt-data` ## Request - Base URL: `https://meterplan.com` - URL: `https://meterplan.com/api/v1/request-smt-data` - Auth: none declared - TypeScript: (a function with typed inputs; its response is checked against the schema) 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](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. ## Request body - object - `esiId` string: 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. - `address` string: 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. - `meterNumber` string, 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. - `currentRetailer` union, required: 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. - 'Abundance Energy' | 'AE Texas' | 'Accent Energy' | 'Ambit Energy' | 'Amigo Energy' | 'Almika Power' | 'Ammper Power' | 'APG&E' | 'Arrow Energy TX' | 'Axpo US' | 'Base Power' | 'BKV Energy' | 'Budget Power' | 'BP Energy Company' | 'BP Energy Retail Company' | 'Branch Energy' | 'Calpine Energy Solutions' | 'Champion Energy Services' | 'Chariot Energy' | 'Cirro Energy' | 'Clearview Energy' | 'CleanSky Energy' | 'Clyde Energy' | 'ConocoPhillips Company' | 'Constellation' | 'David Energy' | 'Direct Energy' | 'Discount Power' | 'Digital Power USA' | 'Eligo Energy' | 'Elevate Energy' | 'ENGIE Resources' | 'Energy Texas' | 'Fanfare Energy' | 'Flagship Power' | 'Freepoint Energy Solutions' | 'Frontier Utilities' | 'Gexa Energy' | 'Good Charlie' | 'Green Mountain Energy' | 'Gridmatic Retail Energy' | 'Grid Power Direct' | 'Heritage Power' | 'Hudson Energy Services' | 'Infuse Energy' | 'Ironhorse Power Services' | 'Just Energy' | 'Light Energy' | 'Maison Energy' | 'Market Place Energy' | 'MEMSIS 1' | 'Meter Energy' | 'Metroplex Energy' | 'MidAmerican Energy Services' | 'MI Texas Rep 4' | 'MI Texas Rep 3' | 'Mothership' | 'National Gas & Electric Texas' | 'NextVolt Texas' | 'Now Power' | 'NRG' | 'Octopus Energy' | 'OhmConnect Energy' | 'OnPoint Energy Texas' | 'Otovo' | 'Payless Power' | 'Penstar Power' | 'Peridot Power' | 'Pogo Energy' | 'Pulse Power' | 'Ranchero Power' | 'Southern Federal Power LLC' | 'Reliant Energy' | 'Rhythm Energy' | 'RPower Retail' | 'SFE Energy Texas' | 'Shell Energy Solutions' | 'SmartEnergy Holdings' | 'SmartestEnergy US' | 'Spark Energy' | 'STAT Energy' | 'Stream Energy' | 'Summer Energy' | 'Tara Energy' | 'Tesla Energy' | 'Texas Retail Energy' | 'Texpo Energy' | 'TotalEnergies Gas & Power North America' | 'Tomorrow Energy Corp' | 'Town Square Energy' | 'TriEagle Energy' | 'True Power' | 'TXU Energy' | 'Value Power' | 'Varsity Energy' | 'TESM' | 'Xoom Energy Texas' | '4Change Energy' - string - `waitSeconds` integer: 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 `200` Tool ran successfully. - object - `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. - `requestId` string, nullable, required: Identifier for this pull. Pass it to get_smt_data. Null only when status is needs_clarification. - `reused` boolean, 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. - `step` string, required: Current processing step, in plain words. - `checkAfterSeconds` number: Present when status is pending: wait about this long before calling get_smt_data. - `esiId` string, nullable, required: ESI ID of the meter. - `utility` string, nullable, required: Utility (TDU) that serves the meter, such as Oncor or CenterPoint, when known. - `serviceAddress` string, nullable, required: Service address on file for this pull, when known. - `dataStart` string, nullable, required: First reading, local Central Time (YYYY-MM-DDTHH:MM:00). - `dataEnd` string, nullable, required: Last reading, local Central Time (YYYY-MM-DDTHH:MM:00). - `readingCount` number, required: Number of 15-minute readings covered. - `monthlyAggregates` object[], required: Per-month totals, oldest first. - `month` string, required: Calendar month, YYYY-MM. - `totalImportsKwh` number, required: Electricity drawn from the grid this month, in kWh. - `totalExportsKwh` number, required: Electricity sent back to the grid this month (solar exports), in kWh. - `netKwh` number, required: Imports minus exports, in kWh. Negative when the home exported more than it used from the grid. - `peakDemandKw` number, required: Highest 15-minute grid import this month, converted to kW. - `daysOfData` number, required: Number of days this month with at least one reading. - `avgMonthlyImportKwh` number, nullable, required: Average grid import per month, in kWh. - `avgMonthlyExportKwh` number, nullable, required: Average grid export (solar sent back) per month, in kWh. - `peakDemandKw` number, nullable, required: Highest 15-minute grid import across the data, in kW. - `hasSolarExports` boolean, nullable, required: True when the meter recorded any exports to the grid. - `intervals` object[]: Raw 15-minute readings, oldest first. Only when includeIntervals is true; capped at the most recent 3,000. - `timestamp` string, required: Interval start, local Central Time wall clock (YYYY-MM-DDTHH:MM:00). - `importKwh` number, required: Grid import during the 15 minutes, in kWh. - `exportKwh` number, required: Grid export during the 15 minutes, in kWh. - `intervalsTruncated` boolean: True when intervals were capped at 3,000. Use the download links for the full year. - `exports` object: Download links for the full year of data. Present when status is complete. Offer csv by default; mention aurora, opensolar, or solargraf only when the user asks for a solar design tool import. - `csv` string, required: Standard CSV download (DateTime, Consumption_kWh, Generation_kWh). - `aurora` string, required: Aurora Solar paste-in file: one consumption value per 15-minute interval. Share only when the user asks for an Aurora file. - `opensolar` string, required: OpenSolar CSV import file. Share only when the user asks for an OpenSolar file. - `solargraf` string, required: Solargraf CSV import file. Share only when the user asks for a Solargraf file. - `errorCode` string: Machine-readable failure reason when status is error, such as smt_agreement_failed or no_data. - `errorMessage` string: What went wrong and what to do next, when status is error. - `candidates` 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. - `esiId` string, required: ESI ID of this meter. Pass it as esiId to request_smt_data once the user confirms. - `formatted` string, required: Full address of this service point, including any unit. - `utility` string, nullable, required: Utility (TDU) serving this meter, when known. - `summary` string, required: One-paragraph plain-language summary of the result. ## Other responses - `400`: Request body was missing, malformed JSON, or failed input schema validation. - `422`: Input was valid but the tool could not complete the request. `message` is safe to show the user. - `500`: Tool execution failed or produced an output that violated the schema. ## Changes - **2026-10-21** `2b73e36f9afd`: 1 info - endpoint added [Operation history](https://skmtc.dev/meterplan/apis/meter-energy-public-api/changes/api/v1/request-smt-data/post.md) --- [API](https://skmtc.dev/meterplan/apis/meter-energy-public-api.md) - [All operations](https://skmtc.dev/meterplan/apis/meter-energy-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/meterplan/apis/meter-energy-public-api/revisions/2b73e36f9afd?raw)