Agentic Platform
Documentation API reference Tools Skills

Tools

Tables Text To Sql

tables_text_to_sql

Convert natural language to SQL queries

This agent converts natural language descriptions into BigQuery SQL query. You can optionally execute the generated query and get results directly.

Playground

Your organization, project and token stay in this browser's local storage and are sent straight to the API — this page never sees them.

POST
item
text_query required Natural language description of the data you want to query. Avoid writing SQL syntax.
max_rows Maximum number of rows to return. Enforces a LIMIT in the SQL and caps results at the API level.
output_fields Optional. Restrict the query output to exactly these column names and no others. Keeps downstream steps stable while the agent stays agnostic. Other columns may still be used in WHERE/ORDER BY/GROUP BY.
config
reasoning_effort Thinking level for the LLM: 'low' for simple queries, 'high' for complex ones
run_query If true, execute the generated query and return results. If false, only return the generated SQL.
allow_empty_results If true, a query returning zero rows is a valid answer. Set it to false in workflows, so the node fails (and retries) instead of passing empty data to the downstream nodes.

Billing

Fixed cost per question asked. The SQL is written by the wrapped assistant, which reads your table schemas and may run the query while it works; running a query is billed on the data it scans, so a question that takes several attempts scans several times.

These usage SKUs can be charged on a call, including SKUs from tools this one may call.

SKU Credits Description Used by
Tool call 1 per request Charged once per successful item, on top of any usage below.
  • This tool
AI web search (Gemini) 14 per query The same, through Gemini's built-in web search. Billed on top of the model's own usage.
AI web search (OpenAI) 10 per query The same, through OpenAI's built-in web search. Billed on top of the model's own usage.
Data scanned 6,250 per TiB scanned Analytical queries are billed on the volume of data the query reads, not on the rows it returns: a narrow filter over a large table can still scan the whole table.
GPT-5 mini (flex), input 125 per million tokens Tokens the model reads from the prompt you send.
GPT-5 mini (flex), output 1,000 per million tokens Tokens the model writes in its answer.
GPT-5 mini (flex), read from cache 12.5 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
GPT-5 mini (standard), input 250 per million tokens Tokens the model reads from the prompt you send.
GPT-5 mini (standard), output 2,000 per million tokens Tokens the model writes in its answer.
GPT-5 mini (standard), read from cache 25 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
GPT-5 nano (flex), input 25 per million tokens Tokens the model reads from the prompt you send.
GPT-5 nano (flex), output 200 per million tokens Tokens the model writes in its answer.
GPT-5 nano (flex), read from cache 2.5 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
GPT-5 nano (standard), input 50 per million tokens Tokens the model reads from the prompt you send.
GPT-5 nano (standard), output 400 per million tokens Tokens the model writes in its answer.
GPT-5 nano (standard), read from cache 5 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
GPT-5.2 (flex), input 875 per million tokens Tokens the model reads from the prompt you send.
GPT-5.2 (flex), output 7,000 per million tokens Tokens the model writes in its answer.
GPT-5.2 (flex), read from cache 87.5 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
GPT-5.2 (standard), input 1,750 per million tokens Tokens the model reads from the prompt you send.
GPT-5.2 (standard), output 14,000 per million tokens Tokens the model writes in its answer.
GPT-5.2 (standard), read from cache 175 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
GPT-5.4 (flex), input 2,500 per million tokens Tokens the model reads from the prompt you send.
GPT-5.4 (flex), output 11,250 per million tokens Tokens the model writes in its answer.
GPT-5.4 (flex), read from cache 250 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
GPT-5.4 (standard), input 5,000 per million tokens Tokens the model reads from the prompt you send.
GPT-5.4 (standard), output 22,500 per million tokens Tokens the model writes in its answer.
GPT-5.4 (standard), read from cache 500 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
GPT-5.4 mini (flex), input 375 per million tokens Tokens the model reads from the prompt you send.
GPT-5.4 mini (flex), output 2,250 per million tokens Tokens the model writes in its answer.
GPT-5.4 mini (flex), read from cache 37.5 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
GPT-5.4 mini (standard), input 750 per million tokens Tokens the model reads from the prompt you send.
GPT-5.4 mini (standard), output 4,500 per million tokens Tokens the model writes in its answer.
GPT-5.4 mini (standard), read from cache 75 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
GPT-5.4 nano (flex), input 100 per million tokens Tokens the model reads from the prompt you send.
GPT-5.4 nano (flex), output 625 per million tokens Tokens the model writes in its answer.
GPT-5.4 nano (flex), read from cache 10 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
GPT-5.4 nano (standard), input 200 per million tokens Tokens the model reads from the prompt you send.
GPT-5.4 nano (standard), output 1,250 per million tokens Tokens the model writes in its answer.
GPT-5.4 nano (standard), read from cache 20 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
GPT-5.5 (flex), input 5,000 per million tokens Tokens the model reads from the prompt you send.
GPT-5.5 (flex), output 22,500 per million tokens Tokens the model writes in its answer.
GPT-5.5 (flex), read from cache 500 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
GPT-5.5 (standard), input 10,000 per million tokens Tokens the model reads from the prompt you send.
GPT-5.5 (standard), output 45,000 per million tokens Tokens the model writes in its answer.
GPT-5.5 (standard), read from cache 1,000 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
GPT-5.6 Luna (flex), input 200 per million tokens Tokens the model reads from the prompt you send.
GPT-5.6 Luna (flex), output 900 per million tokens Tokens the model writes in its answer.
GPT-5.6 Luna (flex), prompt caching 250 per million tokens Tokens written into the prompt cache so later calls can reread them cheaper.
GPT-5.6 Luna (flex), read from cache 20 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
GPT-5.6 Luna (standard), input 400 per million tokens Tokens the model reads from the prompt you send.
GPT-5.6 Luna (standard), output 1,800 per million tokens Tokens the model writes in its answer.
GPT-5.6 Luna (standard), prompt caching 500 per million tokens Tokens written into the prompt cache so later calls can reread them cheaper.
GPT-5.6 Luna (standard), read from cache 40 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
GPT-5.6 Terra (flex), input 2,000 per million tokens Tokens the model reads from the prompt you send.
GPT-5.6 Terra (flex), output 9,000 per million tokens Tokens the model writes in its answer.
GPT-5.6 Terra (flex), prompt caching 2,500 per million tokens Tokens written into the prompt cache so later calls can reread them cheaper.
GPT-5.6 Terra (flex), read from cache 200 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
GPT-5.6 Terra (standard), input 4,000 per million tokens Tokens the model reads from the prompt you send.
GPT-5.6 Terra (standard), output 18,000 per million tokens Tokens the model writes in its answer.
GPT-5.6 Terra (standard), prompt caching 5,000 per million tokens Tokens written into the prompt cache so later calls can reread them cheaper.
GPT-5.6 Terra (standard), read from cache 400 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
Gemini 3 Flash (batch), input 250 per million tokens Tokens the model reads from the prompt you send.
Gemini 3 Flash (batch), output 1,500 per million tokens Tokens the model writes in its answer.
Gemini 3 Flash (batch), read from cache 50 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
Gemini 3 Flash (flex), input 250 per million tokens Tokens the model reads from the prompt you send.
Gemini 3 Flash (flex), output 1,500 per million tokens Tokens the model writes in its answer.
Gemini 3 Flash (flex), read from cache 50 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
Gemini 3 Flash (standard), input 500 per million tokens Tokens the model reads from the prompt you send.
Gemini 3 Flash (standard), output 3,000 per million tokens Tokens the model writes in its answer.
Gemini 3 Flash (standard), read from cache 50 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
Gemini 3.1 Flash Lite (batch), input 125 per million tokens Tokens the model reads from the prompt you send.
Gemini 3.1 Flash Lite (batch), output 750 per million tokens Tokens the model writes in its answer.
Gemini 3.1 Flash Lite (batch), read from cache 12.5 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
Gemini 3.1 Flash Lite (flex), input 125 per million tokens Tokens the model reads from the prompt you send.
Gemini 3.1 Flash Lite (flex), output 750 per million tokens Tokens the model writes in its answer.
Gemini 3.1 Flash Lite (flex), read from cache 12.5 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
Gemini 3.1 Flash Lite (standard), input 250 per million tokens Tokens the model reads from the prompt you send.
Gemini 3.1 Flash Lite (standard), output 1,500 per million tokens Tokens the model writes in its answer.
Gemini 3.1 Flash Lite (standard), read from cache 25 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
Gemini 3.1 Pro (flex), input 2,000 per million tokens Tokens the model reads from the prompt you send.
Gemini 3.1 Pro (flex), output 9,000 per million tokens Tokens the model writes in its answer.
Gemini 3.1 Pro (flex), read from cache 400 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
Gemini 3.1 Pro (standard), input 4,000 per million tokens Tokens the model reads from the prompt you send.
Gemini 3.1 Pro (standard), output 18,000 per million tokens Tokens the model writes in its answer.
Gemini 3.1 Pro (standard), read from cache 400 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
Gemini 3.5 Flash (batch), input 750 per million tokens Tokens the model reads from the prompt you send.
Gemini 3.5 Flash (batch), output 4,500 per million tokens Tokens the model writes in its answer.
Gemini 3.5 Flash (batch), read from cache 75 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
Gemini 3.5 Flash (flex), input 750 per million tokens Tokens the model reads from the prompt you send.
Gemini 3.5 Flash (flex), output 4,500 per million tokens Tokens the model writes in its answer.
Gemini 3.5 Flash (flex), read from cache 80 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
Gemini 3.5 Flash (standard), input 1,500 per million tokens Tokens the model reads from the prompt you send.
Gemini 3.5 Flash (standard), output 9,000 per million tokens Tokens the model writes in its answer.
Gemini 3.5 Flash (standard), read from cache 150 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.

Schemas

item is what you send, config how the tool behaves, and the response is what you get back.

Item

object
Properties
text_query string required

Natural language description of the data you want to query. Avoid writing SQL syntax.

max_rows integer | null

Maximum number of rows to return. Enforces a LIMIT in the SQL and caps results at the API level.

Default: null

output_fields array | null

Optional. Restrict the query output to exactly these column names and no others. Keeps downstream steps stable while the agent stays agnostic. Other columns may still be used in WHERE/ORDER BY/GROUP BY.

Default: null

Example
{
  "text_query": "string",
  "max_rows": null,
  "output_fields": null
}

Configuration

object
Properties
reasoning_effort string

Thinking level for the LLM: 'low' for simple queries, 'high' for complex ones

Values: low high

Default: "low"

run_query boolean

If true, execute the generated query and return results. If false, only return the generated SQL.

Default: true

allow_empty_results boolean

If true, a query returning zero rows is a valid answer. Set it to false in workflows, so the node fails (and retries) instead of passing empty data to the downstream nodes.

Default: true

Example
{
  "reasoning_effort": "low",
  "run_query": true,
  "allow_empty_results": true
}

Response

object
Properties
query string required

The generated BigQuery SQL query

fields array required

Field definitions with name and type (empty if run_query=false)

results array required

Query execution results (empty if run_query=false)

Example
{
  "query": "string",
  "fields": [
    {}
  ],
  "results": [
    {}
  ]
}

Endpoints

POST http://agents.botify.com/{organization}/{project}/tables_text_to_sql/process
POST http://agents.botify.com/{organization}/{project}/tables_text_to_sql/batch_process
POST http://agents.botify.com/{organization}/{project}/tables_text_to_sql/async_process
POST http://agents.botify.com/{organization}/{project}/tables_text_to_sql/async_batch_process

See running a long job in the background for the polling flow.

cURL

curl -X POST "http://agents.botify.com/{organization}/{project}/tables_text_to_sql/process" \
  -H "Authorization: Bearer $BOTIFY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "item": {
    "text_query": "<text_query>"
  }
}'

Raw metadata