Skip to content
GridCapacityAPI.com

Features

Exports

The whole of a query as one file, built in the background: for loading the data into your own model rather than paging through it. Business plan and above.

Create an export

An export is a job. Say what to export (kind), in which format, and with which filters: the query parameters of the matching list route, as a JSON object. The answer is 201 with the job, queued.

curl -X POST "https://api.gridcapacityapi.com/v1/exports" \  -H "Authorization: Bearer gc_live_..." \  -H "Content-Type: application/json" \  -d '{"kind": "capacity_current", "format": "csv", "filters": {"country": "GB", "unit": "MVA"}}'
kindRowsFilters fromFormats
capacity_currentEvery current record matching the filters, with its dimensions, methodology, freshness, provenance and access./v1/capacity/searchCSV, JSON Lines, GeoJSON
capacity_historyEvery observation interval of the matching series. Needs history on the plan as well./v1/substations/{id}/capacity/historyCSV, JSON Lines
substationsSubstations and other assets with their operator, voltage and location precision. No values./v1/substationsCSV, JSON Lines, GeoJSON
changesEvery added, changed, removed and restored series in the window./v1/changesCSV, JSON Lines
  • A filter the list route would refuse, the export refuses when you create it, with the same 400, rather than failing in the background an hour later.
  • Filters that need their own capability still need it: as_of and the history kind need history on the plan, which Business includes.
  • GeoJSON is offered for the kinds whose rows are places: current capacity and assets.

Wait for it

GET /v1/exports/{id} answers with the job. status moves from queued to running to succeeded or failed, and a succeeded export carries its download_url. GET /v1/exports lists yours, newest first.

{
  "data": {
    "id": "exp_01k5…",
    "kind": "capacity_current",
    "format": "csv",
    "filters": {
      "country": "GB",
      "direction": "injection",
      "unit": "MVA"
    },
    "status": "succeeded",
    "row_count": 8365,
    "byte_size": 4812211,
    "error": null,
    "created_at": "2026-09-25T09:00:02Z",
    "started_at": "2026-09-25T09:00:05Z",
    "finished_at": "2026-09-25T09:00:41Z",
    "expires_at": "2026-10-02T09:00:41Z",
    "download_url": "https://…/v1/exports/exp_01k5…/download"
  },
  "meta": {
    "request_id": "req_…"
  }
}

Placeholder values; the shape is the contract.

Download it

curl -L -o capacity.csv "https://api.gridcapacityapi.com/v1/exports/exp_…/download" \  -H "Authorization: Bearer gc_live_..."
  • Until the job has succeeded the download answers 409 export_not_ready, with the job’s status in details.
  • A file is kept for 7 days after it is built, then deleted; after that the download answers 410 export_expired and you create the export again. A file is also expired early when the rights of a source change after it was made, so a withdrawn permission reaches the files already built.
  • At most three exports per account are queued or running at once; a fourth is 429 export_limit_exceeded until one finishes. Downloads are streamed, and a few run at once across the service: one more answers 429 download_limit_exceeded with Retry-After.
  • The dashboard’s exports page creates, lists and downloads the same jobs with your session instead of a key.

Rights travel with the file

An export is built from the same queries as the API’s own routes, so it applies the same rights: a withheld value is withheld in the file too, with its access status and the reason, and each granted row carries its attribution. Where a licence asks for attribution, it asks for it in whatever you build from the file.

An export is not a redistribution licence

A file on your disk is still the operators’ data under the operators’ terms. Passing the dataset on to third parties is an Enterprise term, and only ever as far as each operator’s own licence allows. Rights and licensing.