Natural language.

One required field: nl. Note the name — it is not question or query.

curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/ask" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nl":      "the 5 largest paid orders",
    "schemas": ["shop.orders"]
  }'

result = db.ask("the 5 largest paid orders", schemas=["shop.orders"])

for row in result["rows"]:
    print(row["id"], row["amount_cents"])
print(result["cache"])     # "hit" or "miss"

const result = await db.ask("the 5 largest paid orders", {
  schemas: ["shop.orders"],
});

for (const row of result.rows) console.log(row);
console.log(result.cache);   // "hit" or "miss"

// Go's Ask takes only the question - it sends no schemas allowlist
// and cannot request the plan. Call the endpoint directly if you need those.
resp, err := db.Ask(ctx, "the 5 largest paid orders")
if err != nil {
    return err
}
fmt.Println(resp.Cache, len(resp.Rows))

{
  "rows": [
    { "id": "01JTRX9KQ3YH8K2WMX0F5JZAB7", "customer": "01JTRX1H4Q9P0N2WMX0F5JZ001",
      "amount_cents": 48200, "status": "paid", "placed_ms": 1714478049000 },
    { "id": "01JTRX9KQ3YH8K2WMX0F5JZAC1", "customer": "01JTRX1H4Q9P0N2WMX0F5JZ004",
      "amount_cents": 31150, "status": "paid", "placed_ms": 1714477012000 }
  ],
  "cache": "miss"
}

rows is the answer. cache tells you whether the question was answered from a previously compiled plan ("hit") or compiled fresh ("miss") — a cache hit skips the model entirely and is dramatically faster.

show_plan: true returns the compiled plan alongside the rows. This is the single most useful thing on this page — it is how you check that the question was understood the way you meant it.

curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/ask" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nl":        "the 5 largest paid orders",
    "schemas":   ["shop.orders"],
    "show_plan": true
  }'

# The Python SDK's ask() does not expose show_plan - call the
# endpoint directly when you need the compiled plan back.
import httpx

r = httpx.post(
    f"https://{OC_HOST}/v1/tenants/{OC_TENANT}/ask",
    headers={"Authorization": f"Bearer {OC_TOKEN}"},
    json={
        "nl":        "the 5 largest paid orders",
        "schemas":   ["shop.orders"],
        "show_plan": True,
    },
)
print(r.json()["plan"])

// TypeScript is the only SDK that exposes show_plan.
const result = await db.ask("the 5 largest paid orders", {
  schemas:   ["shop.orders"],
  show_plan: true,
});
console.log(JSON.stringify(result.plan, null, 2));

// The Go SDK cannot send show_plan - its AskResponse.Plan field
// therefore stays empty. Use net/http for the plan.
body, _ := json.Marshal(map[string]any{
    "nl":        "the 5 largest paid orders",
    "schemas":   []string{"shop.orders"},
    "show_plan": true,
})
req, _ := http.NewRequestWithContext(ctx, "POST",
    "https://"+os.Getenv("OC_HOST")+"/v1/tenants/"+os.Getenv("OC_TENANT")+"/ask",
    bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("OC_TOKEN"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)

{
  "rows": [ /* … */ ],
  "cache": "miss",
  "plan": {
    "op": "limit",
    "n":  5,
    "child": {
      "op": "sort",
      "keys": [ { "path": "amount_cents", "order": "desc" } ],
      "child": {
        "op": "filter",
        "predicate": { "op": "eq", "path": "status", "value": "paid" },
        "child": { "op": "scan", "schema": "shop.orders" }
      }
    }
  }
}

Read it inside-out: scan shop.orders, keep rows where status = "paid", sort by amount_cents descending, take 5. That is exactly the question, and you can see it is exactly the question — which is the whole point.

• The plan returned is the post-optimisation one, so it may differ slightly from what the compiler first emitted.
• Adding ?explain to the URL also turns the plan on, and additionally returns an explain field with a cost-annotated tree. Careful: any value enables it — ?explain=false switches it on just as surely as ?explain=true.
• TypeScript is the only SDK that exposes show_plan. Python's ask() has no such parameter; Go's Ask() takes only the question, so its AskResponse.Plan field can never be populated.

Not to SQL. A question compiles to the same internal query plan that a SQL statement compiles to — the structure you saw above. The executor cannot tell which surface produced it, which is why NL inherits the same optimiser and the same execution guarantees as everything else.

There is no SQL string anywhere in the pipeline, so there is nothing to show you if you were looking for "the SQL it wrote". The plan is the compiled query.

Two compilers, in order.

This is worth knowing because it explains a lot of the behaviour:

1. A deterministic rule compiler runs first. It understands a compact grammar — roughly [top N] <table> [where <condition>] [by <sort>] [limit N] — with the operators =, ==, !=, > and <. If your question fits, you get a plan with no model call at all — fast, free and perfectly repeatable.
2. Only if the rule compiler cannot parse the question does it fall through to the managed language model, which emits a plan in the same JSON shape.

Phrasing a question in the rule grammar's shape — "top 5 shop.orders where status = paid by amount_cents desc" — is therefore a real performance technique, not a stylistic one. Note the rule compiler has no >= or <=, cannot mix and with or in one condition, and does no aggregation — those questions go to the model.

What the plan grammar can express.

Omit schemas and every table registered on the instance becomes context. Pass it and only the listed tables are visible. On an instance with more than a handful of tables, scoping is the highest-leverage thing you can do for both accuracy and latency.

# Unscoped - every schema registered on the instance becomes context.
curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/ask" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "nl": "how many orders are unpaid" }'

# Scoped - only these tables are visible to the compiler.
curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/ask" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nl":      "how many orders are unpaid",
    "schemas": ["shop.orders"]
  }'

# Unscoped - every registered schema becomes context.
db.ask("how many orders are unpaid")

# Scoped - only these tables are visible to the compiler.
db.ask("how many orders are unpaid", schemas=["shop.orders"])

// Unscoped - every registered schema becomes context.
await db.ask("how many orders are unpaid");

// Scoped - only these tables are visible to the compiler.
await db.ask("how many orders are unpaid", {
  schemas: ["shop.orders"],
});

// Go's Ask() sends no schemas allowlist, so it always runs unscoped.
// Call the endpoint directly to scope it.
body, _ := json.Marshal(map[string]any{
    "nl":      "how many orders are unpaid",
    "schemas": []string{"shop.orders"},
})
req, _ := http.NewRequestWithContext(ctx, "POST",
    "https://"+os.Getenv("OC_HOST")+"/v1/tenants/"+os.Getenv("OC_TENANT")+"/ask",
    bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("OC_TOKEN"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)

• Ids must be fully qualified — shop.orders, not orders. An id that is not registered is a 400.
• Only names and types are sent — never any of your row data. No sample rows are included in the compiler's context.
• There is no size cap on that context, so an instance with very many tables produces a very large prompt. Scope it.
• Both Python and TypeScript expose schemas. Go does not — its Ask() always runs unscoped.

Compilation problems are all 400s with a compile: prefix. The useful thing is that they are specific — the engine distinguishes "I don't understand this" from "this is ambiguous" from "that table doesn't exist".

An ambiguous question.

If a bare table name matches two namespaces, you get a hard error rather than a guess — and notably, the question is not passed to the model to be resolved. Ambiguity is treated as your intent to name a table, stated imprecisely.

{
  "error": "compile: ambiguous schema \"orders\" — qualify as <namespace>.<table>"
}

A question it cannot compile.

An unsupported aggregation — "the median order value" — or a question the model cannot turn into a valid plan ends here. The model is given up to three attempts, each one shown the previous rejection so it can self-correct; if all three fail you get:

{
  "error": "compile: unparseable natural-language query: …"
}

On a paid instance, three independent limits apply. Because each compile is genuinely expensive, /ask is metered separately from ordinary database calls — running out of NL credit never affects the rest of your database.

Both the concurrency and per-second allowances scale with the configuration you are running — the entry configuration allows 5 questions in flight at once, the standard configuration 15, and the advanced configuration 50. There is no per-day cap; the windows are monthly, instantaneous and per-second, and nothing else.

{
  "error":      "quota_exhausted",
  "resource":   "ask",
  "used":       5000,
  "limit":      5000,
  "message":    "monthly /ask quota exhausted (5000 / 5000). top up credits at
                 https://app.originchain.ai/billing.",
  "top_up_url": "https://app.originchain.ai/billing"
}

{
  "error":         "concurrent_cap_exceeded",
  "resource":      "ask",
  "in_flight":     5,
  "cap":           5,
  "configuration": "entry",
  "msg":           "Tenant has 5 concurrent ask call(s) in flight; the entry
                    configuration allows 5. Wait for in-flight calls to
                    complete or upgrade your configuration."
}

The concurrency rejection carries Retry-After: 1 and is genuinely transient — retry it. The 402 carries no Retry-After, because retrying will not help until credits are topped up. Live in-flight usage is visible on GET /v1/tenants/:tenant/usage.

There is no maximum question length beyond the 8 MB request-body limit — but a long question is not a better one, and everything past the part that names tables and conditions is noise the compiler has to work through.

The most productive pattern is to treat NL as a drafting tool: ask the question with show_plan: true, read the plan to learn what the engine thinks your data means, then write the equivalent SQL and ship that. You get the exploration speed without putting a compile step in your production path.

For a user-facing "ask your data" feature, cache aggressively at your own layer too. Identical questions already hit the engine's plan cache, but the questions real users type are rarely byte-identical.