POST /api/v202609/workbench/query

Executes an ad-hoc KQL query from the Workbench Data Explorer and returns its columns and rows

ExecuteWorkbenchQueryV202609
Use this endpoint to run a hand-written KQL query and get a tabular result back, e.g. Bills | where BillingPeriod == 202608 | summarize sum(TotalCost) by VendorCode. The query is translated to read-only SQL; any attempt to modify data is rejected. Results are capped at the requested limit (default 10,000 rows, maximum 100,000) and truncated is set when more rows were available. Queries time out after 30 seconds. For the list of queryable tables and columns, use GET workbench/schema. A query that cannot be translated or executed returns 400 Bad Request with a user-facing reason in the problem detail. Restricted to ENC staff.

Request Headers

Header Value Required Description
ECI-ApiKey string Yes Your API key. See Authentication.
Content-Type application/json Yes All requests must specify JSON content type, including the request body.

Request Body

EdxQueryRequestV202606
Property Description Type
kql The KQL query text. string
limit Optional row cap (defaults applied server-side; hard-capped at 100k). integer (int32)
Example Request Body application/json 
{  "kql": "string",  "limit": 1
}

Responses

200 OK The request succeeded and the response body contains the requested data.

Response Body Parameters

EdxQueryResultV202606
Property Description Type
columns EdxColumnV202606[]
EdxColumnV202606 properties
Property Description Type
dataType The logical value type used by clients for formatting and data behavior. string
description Human-readable description of the column, when documented in the schema. string
name The result alias or schema field name displayed for this column. string
presentation EdxPresentationV202606
EdxPresentationV202606 properties
Property Description Type
entityType Entity addressed by an entityLink, such as place or meter. Null for presentation formats that do not address an entity. string
format Presentation strategy. Currently the only supported value is entityLink. string
relatedFields Unit fields needed to display this field. EdxRelatedFieldV202606[]
EdxRelatedFieldV202606 properties
Property Description Type
name Name of the related unit field. string
type Display role: unit or unitCode. string
queryTimeMs integer (int64)
render EdxRenderV202606
EdxRenderV202606 properties
Property Description Type
accumulate Optional running-total flag. boolean
chartType Chart kind: columnchart, barchart, timechart, linechart, areachart, piechart, scatterchart, etc. string
kind Optional sub-kind, e.g. “stacked”. string
series Optional series (split-by) columns. string[]
title Optional chart title. string
xColumn Optional explicit category (x-axis) column. string
yColumns Optional explicit value (y-axis) columns. string[]
rowCount integer (int32)
rows Rows, each an array of cell values aligned positionally to EnergyCap.DTO.V202606.EdxQueryResultDTO.Columns. array[]
truncated True when results were capped and more rows exist. boolean
Example Response application/json 
{  "columns": [
    {    "dataType": "string",    "description": "string",    "name": "string",    "presentation": {      "entityType": "string",      "format": "string"
    },    "relatedFields": [
      {      "name": "string",      "type": "string"
    }
    ]
  }
  ],  "queryTimeMs": 1,  "render": {    "accumulate": false,    "chartType": "string",    "kind": "string",    "series": [
      "string"
    ],    "title": "string",    "xColumn": "string",    "yColumns": [
      "string"
    ]
  },  "rowCount": 1,  "rows": [
    [
    {}
  ]
  ],  "truncated": false
}
400 Bad Request The request was malformed or contains invalid parameters. Check the request body and query parameters.

Response Body Parameters

ProblemDetails
Property Description Type
detail string
instance string
status integer (int32)
title string
type string
Example Response application/json 
{  "detail": "string",  "instance": "string",  "status": 1,  "title": "string",  "type": "string"
}