Query live data

The knowledge base knows what your documents say; the data layer knows what your systems report right now. eli.ai bridges them through connectors (scoped, read-only external sources) and named queries(governed, parameterized SQL a human authored). This guide lists what's available, runs a query with full provenance, and then crosses the bridge in one call — a grounded answer that cites both documents and live rows.

Prerequisites

• A key with data:read (list) and data:run (execute).
• At least one connector and one named query configured in the workspace Data page — see Data connectors & domain components.

Discover the surface

List the connectors in scope and the named queries you can run. Secrets never appear — connector rows are credential-masked (hasCredential tells you a secret is stored without revealing it), and what you get back is slugs, titles, descriptions, and parameter specs: exactly what you need to make a call. Queries reference their source by connectorId, so correlate the two lists by id — or filter directly with GET /api/v1/data/queries?connectorId=….

curl -s https://eli.ai/api/v1/data/connectors \
  -H "Authorization: Bearer $ELI_KEY"

{
  "items": [
    {
      "id": "01KY10AAAAAAAAAAAAAAAAAAAA",
      "name": "northwind-ops",
      "kind": "postgres",
      "description": "Order Platform read replica",
      "config": { "host": "replica.internal", "port": 5432, "database": "northwind", "user": "eli_ro" },
      "hasCredential": true,
      "maxRows": 200,
      "timeoutMs": 5000,
      "allowRawSql": false,
      "enabled": true,
      "lastStatus": "ok",
      "lastCheckedAt": "2026-07-21T08:00:00.000Z"
    }
  ],
  "total": 1
}

curl -s https://eli.ai/api/v1/data/queries \
  -H "Authorization: Bearer $ELI_KEY"

{
  "items": [
    {
      "id": "01KY10BBBBBBBBBBBBBBBBBBBB",
      "connectorId": "01KY10AAAAAAAAAAAAAAAAAAAA",
      "slug": "stuck-orders-by-age",
      "title": "Stuck orders by age",
      "description": "Orders in STUCK status, grouped by how long they've been stuck. Use for Order Platform health.",
      "params": [
        {
          "name": "min_hours",
          "type": "number",
          "required": false,
          "default": 24,
          "description": "Only orders stuck at least this many hours."
        }
      ],
      "enabled": true
    }
  ],
  "total": 1
}

Run a query

Call a query by its slug and supply validated params. The response is columns, rows (capped at the connector's maxRows, with a truncated flag), timing, and a dataCallId — the anchor into the append-only provenance trail. Every run, success or failure, writes a data_calls row recording the exact SQL, params, and status.

curl -s -L -X POST https://eli.ai/api/v1/data/queries/stuck-orders-by-age/run \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params":{"min_hours":24}}'

{
  "dataCallId": "01KY10CCCCCCCCCCCCCCCCCCCC",
  "connectorId": "01KYCONNQUERYLIVEDATA00000",
  "queryId": "01KYQRYQUERYLIVEDATA000000",
  "columns": [
    "age_bucket",
    "order_count"
  ],
  "rows": [
    {
      "age_bucket": "24-48h",
      "order_count": 9
    },
    {
      "age_bucket": ">48h",
      "order_count": 5
    }
  ],
  "rowCount": 2,
  "durationMs": 41,
  "truncated": false
}

The bridge — one grounded call

The real payoff is not running SQL yourself — it is letting a natural-language question cross into live data automatically. POST /api/v1/query with includeData: true detects the entities in the question, runs their bound queries as governed lookups, and grounds the answer in both documents ([Sn]) and live rows ([Dn]) — the semantic and data layers fused in a single response.

curl -s -L -X POST https://eli.ai/api/v1/query \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"Is anything stuck on the Order Platform right now?","includeData":true}'

{
  "answer": "The Order Platform currently reports 14 stuck orders in the fulfillment queue [D1]. Per the incident runbook, stuck orders older than 24 hours should be requeued from the fulfillment console [S1].",
  "sources":   [ { "id": "S1", "docTitle": "Order Platform incident runbook", "chunkId": "01KY10BB…" } ],
  "dataCalls": [ { "id": "D1", "dataCallId": "01KY10CC…", "connectorName": "northwind-ops", "queryTitle": "Stuck orders by age", "rowCount": 14, "executedAt": "2026-07-21T09:14:03.412Z" } ]
}

The includeData path runs at most three governed lookups and skips any binding whose parameters would need the model to invent a value — it supplies only entity-name and constant params. For the mechanics of which entities map to which queries, see Entity bindings & live data, and for the full response schema, Structured query (v1).

The leverage

Your documents describe the process; your database knows the current state. This endpoint answers questions that need both — "what's our policy, and are we currently violating it?" — with every number traceable to a logged, read-only query and every recommendation traceable to a source chunk. No dashboards to wire, no SQL in your prompts, and a provenance row behind every figure you can hand to an auditor.