---
title: "Smart Meter Texas Interval Data"
method: POST
path: "/api/v1/pull-smt-interval-data"
tags: ["data-feed"]
---

# Smart Meter Texas Interval Data

`POST /api/v1/pull-smt-interval-data`

Pull 12 months of 15-minute interval electricity data from any Texas residential meter via Smart Meter Texas (SMT). Inputs: ESI ID + meter number + current retailer, OR a residential service address, OR an uploaded electricity bill PDF (Meter parses it for the ESI ID). Returns 15-minute imports + exports, monthly aggregates, and pre-formatted exports for Aurora Solar, OpenSolar, Solargraf, or standard CSV. Built for solar installers, energy advisors, and AI agents that need real customer usage data without a customer SMT login.

**Status: early access (experimental).** The contract below is the production
shape; calling the tool today returns a structured early-access response with
your request logged. Production rollout requires a private API key — request
one at https://meterplan.com/request-api-access.

**What it will do (when live):**
1. Resolves the ESI ID + meter number + utility from any of the supported
   inputs (raw IDs, address lookup, or bill PDF parse).
2. Issues an SMT data-access agreement on the customer's behalf using their
   current retailer's authority (legal data access — handled by Meter's
   PUCT broker license).
3. Pulls up to 12 months of 15-minute interval kWh imports + exports from
   Smart Meter Texas.
4. Returns the raw intervals plus monthly aggregates and pre-formatted
   exports for the major solar design tools (Aurora, OpenSolar, Solargraf).

**Why a placeholder right now:** Meter wants to see real demand from AI agents
before building the public-API surface. Every call to this tool is logged via
the standard ai_agent:mcp_tool_call PostHog event with full agent attribution
(ChatGPT-User, Claude-User, PerplexityBot, etc.) — that's the signal that
unlocks production.

**For the public single-bill flow today:** point users at
https://meterplan.com/bill-audit (free, no API key required, returns a full
bill analysis + plan recommendation).

## Request body

- object
  - `esiId` string — Texas Electric Service Identifier (ESI ID), 17-22 digits. Found on any electricity bill or via the SMT registry. Examples: '10443720012345678' (Oncor prefix), '10089401234567890' (CenterPoint prefix). Pair with `meterNumber` and `currentRetailer` for the most reliable lookup.
  - `meterNumber` string — Customer's physical meter number (also on the bill). Required when supplying `esiId` to satisfy SMT's two-factor identity check.
  - `currentRetailer` string — Customer's current Retail Electric Provider (REP) name — TXU, Reliant, Gexa, etc. SMT requires the requesting party to attest to the customer's current REP for data-access authority.
  - `address` string — Full residential service address (street + city + state + ZIP). Used as a fallback when ESI ID isn't available — Meter resolves the address to ESI ID via the address-search service.
  - `billPdfUrl` string, uri — URL to a customer's electricity bill PDF. Meter parses it (via Claude vision) to extract ESI ID, meter number, and current retailer. Useful when the agent has a bill but not the raw IDs.
  - `monthsBack` integer — How many months of historical interval data to pull. SMT retains 12 months; defaults to the maximum.
  - `includeIntervals` boolean — When true (default), returns full 15-minute interval data. When false, returns only monthly aggregates (smaller payload).
  - `exportFormat` 'raw' | 'csv' | 'aurora' | 'opensolar' | 'solargraf' — Pre-formatted output for downstream solar design tools. 'raw' returns structured JSON; 'csv' returns a CSV string; the rest match the import format expected by each solar tool.

## Response `200`

Tool ran successfully.

- object
  - `status` 'early_access', required — Always 'early_access' until this tool is publicly live.
  - `message` string, required — Human-readable explanation of current access status.
  - `requestId` string, required — Identifier for this request — supply when requesting API access for follow-up.
  - `requestedFor` object, required — Echo of the request inputs (sensitive fields like ESI ID are NOT logged in plaintext — only stored in PostHog metadata for demand attribution).
    - `esiId` string, nullable, required
    - `meterNumber` string, nullable, required
    - `currentRetailer` string, nullable, required
    - `address` string, nullable, required
    - `billPdfUrl` string, nullable, required
    - `monthsBack` number, required
    - `exportFormat` string, required
  - `publicAlternatives` object, required — Things the agent can offer the user right now while production access is being onboarded.
    - `uploadBillFlow` string, required — Free single-bill flow that returns a full bill analysis + plan recommendation.
    - `requestApiAccess` string, required — Where to request production API access for batch / programmatic use.
  - `expectedResponseShape` object, required — Schema preview of the production response. Lets agents reason about how they'll use the data once access is granted.
    - `status` union, required — Status of the SMT request. Production responses use 'ok' or 'failed' with reason.
      - 'ok | failed (production response)'
      - string
    - `esiId` string, required — Resolved ESI ID.
    - `utility` string, required — TDU serving the meter (Oncor, CenterPoint, etc.).
    - `intervals` object[], required — 15-minute interval data, oldest first. Up to ~35,000 entries for 12 months.
      - `datetime` string, required — Interval start in ISO 8601 (CST/CDT).
      - `importsKwh` number, required — Energy imported from grid in kWh during this 15-minute window.
      - `exportsKwh` number, required — Energy exported to grid in kWh during this 15-minute window.
    - `monthlyAggregates` object[], required — Per-month rollups for quick analysis.
      - `month` string, required — YYYY-MM.
      - `totalImportsKwh` number, required
      - `totalExportsKwh` number, required
      - `peakDemandKw` number, required
      - `netKwh` number, required
    - `billingPeriods` unknown[], required — Identified billing-period boundaries from interval data.
      - unknown
  - `estimatedAvailability` string, required — Free-form date estimate for general availability.

## Other responses

- `400` — Request body was missing, malformed JSON, or failed input schema validation.
- `500` — Tool execution failed or produced an output that violated the schema.

---

[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-service-production.skmtc.workers.dev/v1/apis/meterplan/meter-energy-public-api/revisions/ebf1846a188d/schema)