← Ask Your Sheet
API
Tokens

Run Ask Your Sheet from your own code

Both metered lanes are available over HTTP and each returns one JSON object. The division of labour: you send the question and the schema of your table (names, types, row counts and, optionally, value ranges and a few sample rows); the model returns one SQL query, a chart suggestion and notes; you run the SQL on your own data. The rows themselves are never part of the request. The page does exactly this with its in-browser SQL engine.

Base URL and the response shape

Every endpoint lives under https://api.skillsafe.ai/v1/app-api, and every response has one shape:

{ "ok": true,  "data":  { ... } }
{ "ok": false, "error": { "code": "...", "message": "..." } }

The token is minted for this app (the guest call takes {"slug":"ask-your-sheet"}), so no slug header is needed afterwards. Send it as Authorization: Bearer …. The run body is the input object, sent bare.

StatusCodeMeaning
400validation_errorThe body is not a JSON object, or a required key (task, question, schema) is missing.
401unauthorizedNo token, or a stale one. Mint a guest token or sign in again.
402insufficient_creditsThe balance is under min_credits. Price with /estimate first.
403forbiddenA guest token tried to run: both lanes are metered and need a personal sign-in.
404not_foundUnknown job id.
429rate_limitedBack off and retry.
5xxserver_errorTransient. Retry with the same Idempotency-Key so a retry never double-bills.

The task field comes first

task picks the lane. ask turns a question into SQL and a chart. fix repairs SQL that failed, given the error your engine reported - send the failed SQL in context and the message in error. Both lanes reply in the same shape.

The input

Every field is a string. The page builds them with SheetReply.buildInput in sheetreply.js and the schema text with SheetIO.schemaText in sheetio.js.

FieldWhat it holds
taskask or fix. If it is missing or neither, do ask and set "task": "ask".
questionthe person's question, in any language.
schemaone block per table: TABLE name -- N rows, then one line per column: the name exactly as SQL must spell it, its type (NUMBER, TEXT, DATE, TIMESTAMP, BOOLEAN) and, when shared, its range or values.
samplesoptional: the first few rows of each table as CSV. They show formats only; they are not the whole table.
contextoptional: the previous question and the SQL that answered it. When present, the new question is a follow-up: build on that SQL (same filters and grouping unless the question changes them).
errorfix only: the error the page's engine reported for the SQL in context.
retry_noteoptional; if present, your previous reply was unusable - follow it.

The SQL dialect the reply is written in

That dialect is a subset that DuckDB and, for most queries, SQLite and PostgreSQL also accept, so you can run the reply in your own database.

How the model writes the query

The reply

{
  "task": "ask",
  "title": "Revenue by month, 2025",
  "sql": "SELECT ...",
  "chart": {"type": "line", "x": "month", "y": ["revenue"], "series": null, "title": "Monthly revenue"},
  "explanation": "One or two sentences, in the question's language: what the query computes and how - never the numbers, which you have not seen.",
  "assumptions": ["Each assumption you made, one sentence each; empty array when none."],
  "followups": ["Two or three natural next questions this data can answer."],
  "cannot": ""
}

The fix lane adds fixed: one sentence on what was wrong and what changed. When the data cannot answer the question, sql is empty and cannot says why.

The chart field

chart.type is one of: bar (categories, vertical), hbar (long labels or more than 12 categories), line (a trend over time or an ordered number), area (a cumulative or stacked-feeling trend), scatter (two numbers per row), pie (shares of one whole, at most 8 slices, no negatives), number (a single-row result of one to four headline numbers), table (no sensible chart). chart.x is the result column for the axis or slices, chart.y an array of result number columns, chart.series an optional result text column to split lines or bars by (at most 10 values), chart.title a short title. Every name must be a column alias of your SELECT, spelled exactly.

Worked examples - every lane, every sample

These are the page's free samples. Each input is exactly what the page sends; each reply is the saved answer the page replays; the result line is what the page's engine returns when it runs the SQL on the sample data.

Coffee chain sales - Revenue by month and store (ask)

Input:

{
  "task": "ask",
  "question": "What is total revenue by month, split by store?",
  "schema": "TABLE coffee_sales -- 1741 rows\n  order_id NUMBER -- range 10001 to 11741, mean 10871\n  order_date DATE -- from 2025-01-01 to 2025-12-31\n  store TEXT -- 4 values: 'Downtown', 'University', 'Harbor', 'Airport'\n  category TEXT -- 5 values: 'Espresso', 'Pastry', 'Brew', 'Tea', 'Merch'\n  item TEXT -- 18 distinct values\n  qty NUMBER -- range 1 to 3, mean 1.628\n  unit_price NUMBER -- range 2.9 to 18.6, mean 4.638\n  revenue NUMBER -- range 2.9 to 18.6, mean 7.263\n  payment TEXT -- 3 values: 'Card', 'App', 'Cash'\n  loyalty_member BOOLEAN -- true/false",
  "samples": "-- coffee_sales: first 5 of 1741 rows\norder_id,order_date,store,category,item,qty,unit_price,revenue,payment,loyalty_member\n10001,2025-01-01,Downtown,Espresso,Latte,2,4.6,9.2,Card,true\n10002,2025-01-01,University,Merch,Beans 250g,1,12.5,12.5,Cash,false\n10003,2025-01-01,Harbor,Espresso,Mocha,1,5.1,5.1,Cash,true\n10004,2025-01-01,Harbor,Pastry,Blueberry Muffin,1,3.3,3.3,Card,true\n10005,2025-01-01,Airport,Pastry,Croissant,3,4.2,12.6,Card,true"
}

Reply:

{
  "task": "ask",
  "title": "Revenue by month and store, 2025",
  "sql": "SELECT DATE_TRUNC('month', order_date) AS month,\n       store,\n       ROUND(SUM(revenue), 2) AS revenue\nFROM coffee_sales\nGROUP BY 1, 2\nORDER BY month, store",
  "chart": {
    "type": "line",
    "x": "month",
    "y": [
      "revenue"
    ],
    "series": "store",
    "title": "Monthly revenue by store"
  },
  "explanation": "Adds up the revenue of every order line per calendar month and store, one row per month and store, ordered by month.",
  "assumptions": [
    "Revenue means the revenue column as recorded (quantity times unit price), with no adjustment for refunds.",
    "Months are calendar months of order_date."
  ],
  "followups": [
    "Which store grew the most between the first and second half of the year?",
    "What is the average order value per store each month?",
    "How does weekend revenue compare with weekday revenue for each store?"
  ],
  "cannot": ""
}

Result: 48 rows, columns month, store, revenue; first rows [["2025-01-01", "Airport", 257.5], ["2025-01-01", "Downtown", 487.1], ["2025-01-01", "Harbor", 237.6]]

Coffee chain sales - Top 10 items and their share (ask)

Input:

{
  "task": "ask",
  "question": "Which 10 items bring in the most revenue, and what share of all revenue is each?",
  "schema": "TABLE coffee_sales -- 1741 rows\n  order_id NUMBER -- range 10001 to 11741, mean 10871\n  order_date DATE -- from 2025-01-01 to 2025-12-31\n  store TEXT -- 4 values: 'Downtown', 'University', 'Harbor', 'Airport'\n  category TEXT -- 5 values: 'Espresso', 'Pastry', 'Brew', 'Tea', 'Merch'\n  item TEXT -- 18 distinct values\n  qty NUMBER -- range 1 to 3, mean 1.628\n  unit_price NUMBER -- range 2.9 to 18.6, mean 4.638\n  revenue NUMBER -- range 2.9 to 18.6, mean 7.263\n  payment TEXT -- 3 values: 'Card', 'App', 'Cash'\n  loyalty_member BOOLEAN -- true/false",
  "samples": "-- coffee_sales: first 5 of 1741 rows\norder_id,order_date,store,category,item,qty,unit_price,revenue,payment,loyalty_member\n10001,2025-01-01,Downtown,Espresso,Latte,2,4.6,9.2,Card,true\n10002,2025-01-01,University,Merch,Beans 250g,1,12.5,12.5,Cash,false\n10003,2025-01-01,Harbor,Espresso,Mocha,1,5.1,5.1,Cash,true\n10004,2025-01-01,Harbor,Pastry,Blueberry Muffin,1,3.3,3.3,Card,true\n10005,2025-01-01,Airport,Pastry,Croissant,3,4.2,12.6,Card,true"
}

Reply:

{
  "task": "ask",
  "title": "Top 10 items by revenue and their share of the total",
  "sql": "SELECT item,\n       category,\n       ROUND(SUM(revenue), 2) AS revenue,\n       ROUND(100.0 * SUM(revenue) / SUM(SUM(revenue)) OVER (), 2) AS share_pct\nFROM coffee_sales\nGROUP BY item, category\nORDER BY revenue DESC\nLIMIT 10",
  "chart": {
    "type": "hbar",
    "x": "item",
    "y": [
      "revenue"
    ],
    "series": null,
    "title": "Top 10 items by revenue"
  },
  "explanation": "Totals revenue per item, computes each item's percentage of revenue across all items before the top 10 are taken, then keeps the ten largest.",
  "assumptions": [
    "The share is of all revenue in the table, not only of the top 10."
  ],
  "followups": [
    "Which category earns the most per order line?",
    "How does the top item's revenue change month by month?",
    "Which items sell most often in quantity rather than revenue?"
  ],
  "cannot": ""
}

Result: 10 rows, columns item, category, revenue, share_pct; first rows [["Cappuccino", "Espresso", 1391.4, 11], ["Mocha", "Espresso", 1257, 9.94], ["Latte", "Espresso", 1165.4, 9.22]]

Company roster - Median vs average salary (ask)

Input:

{
  "task": "ask",
  "question": "What are the median and average salary in each department?",
  "schema": "TABLE employees -- 240 rows\n  employee_id TEXT -- 240 distinct values\n  department TEXT -- 6 values: 'Engineering', 'Sales', 'Support', 'Marketing', 'Operations', 'Finance'\n  level TEXT -- 5 values: 'L2', 'L1', 'L3', 'L4', 'L5'\n  hire_date DATE -- from 2011-05-02 to 2025-08-24\n  salary NUMBER -- range 47000 to 193000, mean 101331.25\n  office TEXT -- 4 values: 'Lisbon', 'Toronto', 'Remote', 'Singapore'\n  performance_rating NUMBER -- range 2 to 5, mean 3.133\n  manager BOOLEAN -- true/false",
  "samples": "-- employees: first 5 of 240 rows\nemployee_id,department,level,hire_date,salary,office,performance_rating,manager\nE1000,Marketing,L2,2020-06-21,86000,Toronto,3,false\nE1001,Sales,L3,2019-06-04,120500,Remote,3,false\nE1002,Finance,L1,2024-01-28,76500,Lisbon,2,false\nE1003,Engineering,L1,2024-05-20,99000,Toronto,4,false\nE1004,Engineering,L4,2024-06-25,155500,Lisbon,4,true"
}

Reply:

{
  "task": "ask",
  "title": "Median and average salary by department",
  "sql": "SELECT department,\n       COUNT(*) AS employees,\n       MEDIAN(salary) AS median_salary,\n       ROUND(AVG(salary), 2) AS avg_salary\nFROM employees\nGROUP BY department\nORDER BY median_salary DESC",
  "chart": {
    "type": "bar",
    "x": "department",
    "y": [
      "median_salary",
      "avg_salary"
    ],
    "series": null,
    "title": "Median vs average salary by department"
  },
  "explanation": "Groups employees by department and computes the headcount, the median salary and the mean salary in each, ranked by the median.",
  "assumptions": [
    "Salary is annual and in one currency for everyone."
  ],
  "followups": [
    "How does median salary rise from level L1 to L5 in each department?",
    "Which offices pay above the company median?",
    "What is the salary spread (standard deviation) per department?"
  ],
  "cannot": ""
}

Result: 6 rows, columns department, employees, median_salary, avg_salary; first rows [["Engineering", 75, 129500, 133800], ["Finance", 13, 106500, 114346.15], ["Marketing", 34, 93750, 94411.76]]

Company roster - Salary vs years since hire (ask)

Input:

{
  "task": "ask",
  "question": "Plot salary against years since hire for every employee, colored by department.",
  "schema": "TABLE employees -- 240 rows\n  employee_id TEXT -- 240 distinct values\n  department TEXT -- 6 values: 'Engineering', 'Sales', 'Support', 'Marketing', 'Operations', 'Finance'\n  level TEXT -- 5 values: 'L2', 'L1', 'L3', 'L4', 'L5'\n  hire_date DATE -- from 2011-05-02 to 2025-08-24\n  salary NUMBER -- range 47000 to 193000, mean 101331.25\n  office TEXT -- 4 values: 'Lisbon', 'Toronto', 'Remote', 'Singapore'\n  performance_rating NUMBER -- range 2 to 5, mean 3.133\n  manager BOOLEAN -- true/false",
  "samples": "-- employees: first 5 of 240 rows\nemployee_id,department,level,hire_date,salary,office,performance_rating,manager\nE1000,Marketing,L2,2020-06-21,86000,Toronto,3,false\nE1001,Sales,L3,2019-06-04,120500,Remote,3,false\nE1002,Finance,L1,2024-01-28,76500,Lisbon,2,false\nE1003,Engineering,L1,2024-05-20,99000,Toronto,4,false\nE1004,Engineering,L4,2024-06-25,155500,Lisbon,4,true"
}

Reply:

{
  "task": "ask",
  "title": "Salary against years since hire",
  "sql": "SELECT employee_id,\n       department,\n       ROUND(DATE_DIFF('day', hire_date, CURRENT_DATE) / 365.25, 1) AS years_since_hire,\n       salary\nFROM employees\nWHERE hire_date IS NOT NULL AND salary IS NOT NULL\nORDER BY years_since_hire",
  "chart": {
    "type": "scatter",
    "x": "years_since_hire",
    "y": [
      "salary"
    ],
    "series": "department",
    "title": "Salary vs years since hire"
  },
  "explanation": "Computes each employee's years since hire from hire_date to today and lists it next to their salary and department, one row per employee.",
  "assumptions": [
    "Years since hire is measured to today's date, in years of 365.25 days.",
    "Employees missing a hire date or salary are left out."
  ],
  "followups": [
    "What is the average salary for each year of tenure?",
    "Do managers earn more than non-managers at the same level?",
    "Which department has the newest hires on average?"
  ],
  "cannot": ""
}

Result: 240 rows, columns employee_id, department, years_since_hire, salary; first rows [["E1016", "Marketing", 1.2, 64500], ["E1094", "Operations", 1.2, 70000], ["E1199", "Marketing", 1.2, 72500]]

Company roster - A question the data cannot answer (ask)

Input:

{
  "task": "ask",
  "question": "Which employees are most likely to quit next year?",
  "schema": "TABLE employees -- 240 rows\n  employee_id TEXT -- 240 distinct values\n  department TEXT -- 6 values: 'Engineering', 'Sales', 'Support', 'Marketing', 'Operations', 'Finance'\n  level TEXT -- 5 values: 'L2', 'L1', 'L3', 'L4', 'L5'\n  hire_date DATE -- from 2011-05-02 to 2025-08-24\n  salary NUMBER -- range 47000 to 193000, mean 101331.25\n  office TEXT -- 4 values: 'Lisbon', 'Toronto', 'Remote', 'Singapore'\n  performance_rating NUMBER -- range 2 to 5, mean 3.133\n  manager BOOLEAN -- true/false",
  "samples": "-- employees: first 5 of 240 rows\nemployee_id,department,level,hire_date,salary,office,performance_rating,manager\nE1000,Marketing,L2,2020-06-21,86000,Toronto,3,false\nE1001,Sales,L3,2019-06-04,120500,Remote,3,false\nE1002,Finance,L1,2024-01-28,76500,Lisbon,2,false\nE1003,Engineering,L1,2024-05-20,99000,Toronto,4,false\nE1004,Engineering,L4,2024-06-25,155500,Lisbon,4,true"
}

Reply:

{
  "task": "ask",
  "title": "Likelihood of leaving next year",
  "sql": "",
  "chart": {
    "type": "table",
    "x": null,
    "y": [],
    "series": null,
    "title": ""
  },
  "explanation": "The data has no record of who has left, resignations or engagement, so there is nothing to learn quitting from.",
  "assumptions": [],
  "followups": [
    "How many employees were hired in each year?",
    "Which departments have the lowest average performance rating?",
    "How many employees in each level have been here under two years?"
  ],
  "cannot": "Predicting who will quit needs past departures or signals such as engagement, and this table has neither - only department, level, hire date, salary, office, rating and the manager flag. A close question it can answer: tenure and rating by department."
}

Result: no SQL - the reply explains why the data cannot answer.

Website traffic - 7-day average of signups (ask)

Input:

{
  "task": "ask",
  "question": "Show the 7-day moving average of daily signups across all channels.",
  "schema": "TABLE web_traffic -- 1365 rows\n  \"date\" DATE -- from 2025-01-01 to 2025-09-30\n  channel TEXT -- 5 values: 'Email', 'Organic', 'Paid', 'Referral', 'Social'\n  sessions NUMBER -- range 101 to 1432, mean 499.752\n  signups NUMBER -- range 3 to 52, mean 13.108\n  ad_spend NUMBER -- range 0 to 1564.2, mean 172.174\n  revenue NUMBER -- range 53.79 to 1507.84, mean 332.29",
  "samples": "-- web_traffic: first 5 of 1365 rows\ndate,channel,sessions,signups,ad_spend,revenue\n2025-01-01,Organic,950,16,0,313.13\n2025-01-01,Paid,461,17,495.15,347.19\n2025-01-01,Social,408,5,150.61,134.65\n2025-01-01,Email,232,10,0,344.75\n2025-01-01,Referral,163,6,0,146.16"
}

Reply:

{
  "task": "ask",
  "title": "7-day moving average of daily signups",
  "sql": "WITH daily AS (\n  SELECT \"date\", SUM(signups) AS signups\n  FROM web_traffic\n  GROUP BY \"date\"\n)\nSELECT \"date\",\n       signups,\n       ROUND(AVG(signups) OVER (ORDER BY \"date\" ROWS BETWEEN 6 PRECEDING AND CURRENT ROW), 2) AS signups_7d_avg\nFROM daily\nORDER BY \"date\"",
  "chart": {
    "type": "line",
    "x": "date",
    "y": [
      "signups",
      "signups_7d_avg"
    ],
    "series": null,
    "title": "Daily signups and 7-day average"
  },
  "explanation": "Adds up signups across channels for each day, then averages each day with the six days before it.",
  "assumptions": [
    "The first six days average over fewer than seven days.",
    "Days with no rows are not filled in as zero."
  ],
  "followups": [
    "Which channel's signups grew fastest over the period?",
    "What is the signup rate (signups per session) by channel each month?",
    "Which weekday brings the most signups?"
  ],
  "cannot": ""
}

Result: 273 rows, columns date, signups, signups_7d_avg; first rows [["2025-01-01", 54, 54], ["2025-01-02", 56, 55], ["2025-01-03", 56, 55.33]]

Website traffic - Share of sessions by channel (ask)

Input:

{
  "task": "ask",
  "question": "What share of sessions comes from each channel?",
  "schema": "TABLE web_traffic -- 1365 rows\n  \"date\" DATE -- from 2025-01-01 to 2025-09-30\n  channel TEXT -- 5 values: 'Email', 'Organic', 'Paid', 'Referral', 'Social'\n  sessions NUMBER -- range 101 to 1432, mean 499.752\n  signups NUMBER -- range 3 to 52, mean 13.108\n  ad_spend NUMBER -- range 0 to 1564.2, mean 172.174\n  revenue NUMBER -- range 53.79 to 1507.84, mean 332.29",
  "samples": "-- web_traffic: first 5 of 1365 rows\ndate,channel,sessions,signups,ad_spend,revenue\n2025-01-01,Organic,950,16,0,313.13\n2025-01-01,Paid,461,17,495.15,347.19\n2025-01-01,Social,408,5,150.61,134.65\n2025-01-01,Email,232,10,0,344.75\n2025-01-01,Referral,163,6,0,146.16"
}

Reply:

{
  "task": "ask",
  "title": "Share of sessions by channel",
  "sql": "SELECT channel,\n       SUM(sessions) AS sessions,\n       ROUND(100.0 * SUM(sessions) / (SELECT SUM(sessions) FROM web_traffic), 2) AS share_pct\nFROM web_traffic\nGROUP BY channel\nORDER BY sessions DESC",
  "chart": {
    "type": "pie",
    "x": "channel",
    "y": [
      "sessions"
    ],
    "series": null,
    "title": "Sessions by channel"
  },
  "explanation": "Totals sessions for each channel over the whole period and divides by all sessions to give each channel's percentage.",
  "assumptions": [
    "The share covers every date in the table."
  ],
  "followups": [
    "How did each channel's share of sessions change month by month?",
    "Which channel converts sessions to signups best?",
    "What is the revenue per session for each channel?"
  ],
  "cannot": ""
}

Result: 5 rows, columns channel, sessions, share_pct; first rows [["Organic", 276114, 40.48], ["Paid", 175726, 25.76], ["Social", 116619, 17.1]]

Website traffic - Fix a query that fails (fix)

Input:

{
  "task": "fix",
  "question": "Cost per signup by channel for paid traffic",
  "schema": "TABLE web_traffic -- 1365 rows\n  \"date\" DATE -- from 2025-01-01 to 2025-09-30\n  channel TEXT -- 5 values: 'Email', 'Organic', 'Paid', 'Referral', 'Social'\n  sessions NUMBER -- range 101 to 1432, mean 499.752\n  signups NUMBER -- range 3 to 52, mean 13.108\n  ad_spend NUMBER -- range 0 to 1564.2, mean 172.174\n  revenue NUMBER -- range 53.79 to 1507.84, mean 332.29",
  "samples": "-- web_traffic: first 5 of 1365 rows\ndate,channel,sessions,signups,ad_spend,revenue\n2025-01-01,Organic,950,16,0,313.13\n2025-01-01,Paid,461,17,495.15,347.19\n2025-01-01,Social,408,5,150.61,134.65\n2025-01-01,Email,232,10,0,344.75\n2025-01-01,Referral,163,6,0,146.16",
  "context": "Previous question: Cost per signup by channel for paid traffic\nPrevious SQL:\nSELECT channel, SUM(spend) / SUM(signups) AS cost_per_signup\nFROM web_traffic\nWHERE spend > 0\nGROUP BY channel\nORDER BY cost_per_signup",
  "error": "No column named \"spend\". Did you mean \"ad_spend\"? Columns here: date, channel, sessions, signups, ad_spend, revenue. Names with spaces or capitals need double quotes."
}

Reply:

{
  "task": "fix",
  "title": "Cost per signup by channel for paid traffic",
  "sql": "SELECT channel,\n       ROUND(SUM(ad_spend) / SUM(signups), 2) AS cost_per_signup\nFROM web_traffic\nWHERE ad_spend > 0\nGROUP BY channel\nORDER BY cost_per_signup",
  "chart": {
    "type": "bar",
    "x": "channel",
    "y": [
      "cost_per_signup"
    ],
    "series": null,
    "title": "Cost per signup, paid channels"
  },
  "explanation": "Divides each channel's total ad spend by its total signups, counting only days with spend, cheapest first.",
  "assumptions": [
    "Paid traffic means rows where ad_spend is above zero."
  ],
  "followups": [
    "How did cost per signup for Paid change month by month?",
    "What is the revenue per unit of ad spend by channel?"
  ],
  "cannot": "",
  "fixed": "The table has no column named spend - the spend column is ad_spend, so both references now use it, and the ratio is rounded to cents."
}

Result: 2 rows, columns channel, cost_per_signup; first rows [["Social", 29.36], ["Paid", 32.99]]

Step 1 — a tiny client helper

One function that sends JSON and unwraps the response. Paste a personal token from /tokens.html, or leave it empty and mint a guest token in step 2.

BASE="https://api.skillsafe.ai/v1/app-api"
TOKEN="paste-your-token-here"   # from https://ask-your-sheet.skillsafe.ai/tokens.html
api() { # api METHOD PATH [JSON-BODY]
  curl -s -X "$1" "$BASE$2" -H "Content-Type: application/json" \
    ${TOKEN:+-H "Authorization: Bearer $TOKEN"} ${3:+--data "$3"}
}

Step 2 — a token

A guest token is enough for /me and /estimate. A run is metered, so it needs a personal token: sign in on /tokens.html and copy it from there.

# a guest token (enough for /me and /estimate); a run needs your personal token from /tokens.html
TOKEN=$(curl -s -X POST "$BASE/guest" -H "Content-Type: application/json" -d '{"slug":"ask-your-sheet"}' | jq -r '.data.token')

Step 3 — GET /me

Who the token is (subject_type: user or guest) and the credit balance.

api GET /me | jq '.data | {subject_type, credits}'

Step 4 — POST /estimate

Free. The body is the run input itself, the bare object (never wrapped in {"input": ...}). hold_credits is a reservation, not the price; min_credits is what the balance must cover; model_alias reads gpt-terra.

# input.json: the run input object - {"task": "ask", "question": "...", "schema": "TABLE ...", "samples": "..."}
# - see the input table
api POST /estimate "$(cat input.json)" | jq '.data | {hold_credits, min_credits, model, model_alias, markup_bps, warnings}'

Step 5 — POST /run, then poll the job

Send an Idempotency-Key built from the lane and the input: a retry with the same key never bills twice. The page uses ask-your-sheet:<task>:<inputHash>:a<attempt> - the lane is part of the key - and its one automatic reformat retry is a new attempt number, named in the page as one extra run. Both lanes reply with title, sql, chart, explanation, assumptions, followups and cannot (plus fixed on a fix). The code below prints the SQL to run, the chart and the explanation.

KEY="ask-your-sheet:ask:$(shasum -a 256 input.json | cut -c1-16):a1"
JOB=$(curl -s -X POST "$BASE/run" -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $KEY" --data @input.json | jq -r '.data.job_id')
while :; do
  J=$(api GET "/jobs/$JOB"); S=$(echo "$J" | jq -r '.data.status')
  case "$S" in succeeded|failed|cancelled) break;; esac; sleep 2
done
echo "$J" | jq -r '.data.output.output' > reply.json   # one JSON object, the reply contract
echo "$J" | jq '.data | {charged_credits, truncated}'
jq -r '.sql, .explanation, (.assumptions[]? | "- " + .), .cannot' reply.json   # run the SQL on your own data

Step 6 — POST /run-stream

The same run as Server-Sent Events, with the same input.json. Browsers receive progress ticks rather than text deltas; the final done event carries the reply.

# Server-Sent Events: tick/delta events while the job runs, then a final event with the job
curl -N -s -X POST "$BASE/run-stream" -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: ask-your-sheet:ask:$(shasum -a 256 input.json | cut -c1-16):a1" --data @input.json