Historical Backfill

Load past energy data for connected devices so your history doesn't start at connection time

When you connect a device to Texture, live polling begins immediately and metrics start accumulating from that moment forward. Historical backfill fills in the data that existed before the connection — pulling past production, consumption, storage, and grid energy directly from the manufacturer's API and writing it into Texture as if it had always been there.

This is what lets a newly onboarded fleet show a full year of generation history on day one, or lets a program operator reconstruct a baseline for devices that were enrolled retroactively.

Why Historical Backfill?#

Live polling answers "what is this device doing now?" Backfill answers "what was it doing last month, last quarter, last year?" Common reasons to use it:

• Program baselines — Reconstruct device behavior for the period a program requires (e.g. a full calendar month) for devices enrolled after the fact.
• Retroactive onboarding — A customer connects an existing fleet and expects to see history, not an empty chart.
• Analytics and reporting — Trend analysis, performance baselines, and savings calculations that need data predating the connection.
• Gap filling — Recover periods where live polling was interrupted.

Once backfilled, historical data is queryable through the same Metrics API as live data — there is no separate "historical" endpoint to read from.

How It Works#

Backfill is an explicit, range-bound operation. You choose which devices to backfill and for what time window — there is no automatic "backfill everything" behavior. This keeps the operation safe: it never silently floods a manufacturer's API or competes with live polling.

At a high level:

1. A backfill is requested for a set of devices and a start/end time range.
2. Texture resolves each device to its underlying manufacturer connection and fans out one job per connection.
3. A manufacturer-specific coordinator splits the requested range into chunks the OEM API allows (for example 7-day or 1-day windows), respecting that OEM's rate limits.
4. Each chunk is fetched, the raw response is archived, and the normalized data is written into Texture's time-series store with an ingestType of backfill.
5. The data becomes available through the standard Metrics API.

Idempotency#

Backfills are safe to re-run. Each finished backfill is recorded per device and time window, so re-requesting a window that has already completed is skipped rather than duplicated. A previously failed window is not skipped — re-requesting it simply retries.

Manufacturer Support & Quirks#

Historical backfill is available for the manufacturers below. Because each OEM exposes historical data differently, the available lookback, data granularity, and chunking differ per manufacturer. Texture handles the chunking and rate limiting automatically — the table is here so you know what to expect from the resulting data.

Unsupported manufacturers#

Manufacturers without historical backfill support (for example Generac, Emporia, SMA, and thermostat/EV-charger integrations) are skipped, not errored. If a backfill request includes a mix of supported and unsupported devices, the supported ones proceed and the unsupported ones are reported as skipped.

Requesting a Backfill#

A backfill is triggered by specifying a batch of devices and a time window. There are two ways to do this.

Option 1 — Request through Texture#

During the current rollout, Texture runs backfills on your behalf. Send your Texture contact (or support):

• the manufacturer,
• the device or system identifiers (Texture device IDs, or the OEM site IDs / serial numbers),
• the start and end dates of the window you need.

Texture validates the request, clamps it to the manufacturer's retention limit, and runs it. This is the recommended path today and requires no code.

Option 2 — Trigger via the API#

Backfills are triggered with the triggerHistoricalBackfill GraphQL mutation on the Texture supergraph. You pass a batch of Texture device IDs (not OEM-side identifiers — Texture resolves each device to its manufacturer connection and system identifier for you) and an explicit time window. The mutation returns immediately with an operationId; the actual fetching happens asynchronously.

mutation BackfillApril($input: TriggerHistoricalBackfillInput!) {
  triggerHistoricalBackfill(input: $input) {
    success
    message
    operationId
    connectionsQueued
    connectionsSkipped {
      id
      reason
    }
  }
}

{
  "input": {
    "workspaceId": "cmcxv8qu8000zxkikt3g7esnu",
    "deviceIds": [
      "cmd8fgy611akwjv1qoupv6ujk",
      "cmo35zul60720gm1s6kxoh248",
      "cmgo4pmme1hwoi01qcng1j2yr"
    ],
    "startTime": "2026-04-01T00:00:00Z",
    "endTime": "2026-05-01T00:00:00Z"
  }
}

Input parameters

A successful response looks like this — note that backfill uses partial-success semantics: devices that can't be queued are returned in connectionsSkipped rather than failing the whole call.

{
  "data": {
    "triggerHistoricalBackfill": {
      "success": true,
      "message": "Queued 2 of 3 devices",
      "operationId": "op_2x9c1f3b8a",
      "connectionsQueued": 2,
      "connectionsSkipped": [
        { "id": "cmo35zul60720gm1s6kxoh248", "reason": "COORDINATOR_NOT_AVAILABLE" }
      ]
    }
  }
}

Skip reason codes (connectionsSkipped[].reason):

Checking Backfill Status#

The mutation returns an operationId that ties together every device queued by a single call. Because fetching is asynchronous, completion is tracked separately. The simplest confirmation is to query the Metrics API for the backfilled window and watch the data appear as chunks finish.

Texture also records the outcome of every finished backfill (per device and window, SUCCESS or FAILURE) keyed by that operationId, so your Texture contact can report on progress, per-system coverage, and any failures for a given operation.

Retrieving Backfilled Data#

Backfilled data is not read from a special endpoint — it lands in the same time-series store as live data and is queried through the standard Metrics API. Once a backfill completes, query the metric you need over the historical range. You can request multiple devices in one call by repeating the filterDeviceId[] parameter.

GET /v1/metrics/generation

curl -X GET "https://api.texturehq.com/v1/metrics/generation?filterDeviceId[]=cmd8fgy611akwjv1qoupv6ujk&filterDeviceId[]=cmgo4pmme1hwoi01qcng1j2yr&filterRangeAfter=2026-04-01T00:00:00Z&filterRangeBefore=2026-05-01T00:00:00Z&windowSize=DAY" \
  -H "Texture-Api-Key: your_api_key"

The response shape, window sizes (FIFTEEN_MINUTES, HOUR, DAY, WEEK, MONTH, YEAR), and filtering options are identical to those documented in the Metrics reference. Note that the resolution you can meaningfully request is bounded by the manufacturer's native granularity — a daily-granularity OEM (FranklinWH, EG4) will not produce 15-minute detail for backfilled periods, so request DAY windows for those.

Best Practices#

• Pass Texture device IDs, not OEM identifiers. The mutation takes Device.id values and resolves each to its manufacturer connection automatically.
• Remember endTime is exclusive. To backfill all of April, use 2026-04-01T00:00:00Z → 2026-05-01T00:00:00Z.
• Batch and pace large fleets. Up to 1000 devices per call, but ramp batch size (1 → 10 → 50) and space calls out so you don't exhaust OEM rate limits or contend with live polling.
• Know the retention cap before you ask. Don't expect data older than the manufacturer's window (2 years for Enphase, ~12 months for Tesla and EG4).
• Match query granularity to the source. Use larger windowSize values (DAY, WEEK) for daily-granularity OEMs like FranklinWH and EG4.
• Re-running is safe. Backfills are idempotent; completed windows are skipped, failed windows retry.
• Combine with live data freely. Backfilled and live metrics share the same store and query path — no special handling needed in your application.

Next Steps#

• Read the Metrics API reference to query backfilled data
• Explore the full API
• Review per-manufacturer integration details
• Contact Texture to request a backfill for your devices

Historical backfill closes the gap between when a device started reporting to its manufacturer and when it connected to Texture — giving you complete, queryable history across your fleet.