Agentic Platform
Documentation API reference Tools Skills

Tools

Tables Query

tables_query MCP

Query any table in the data model with BigQuery Standard SQL syntax. Always prefix tables with "catalog." (ex: catalog.crawl_pages_20251201).

Query any data-model table with BigQuery Standard SQL syntax. Always prefix tables with "catalog." (for example, catalog.crawl_pages_20251201). The following query-string functions are supported: - query_string_keys(input): returns ARRAY<STRING> with query-string keys. - query_string_params(input): returns ARRAY<STRUCT<key STRING, value STRING>> with query-string key/value pairs. - remove_query_string(url, keys): removes URL query-string parameters whose keys are in an ARRAY<STRING>. It removes the "?" when no parameter remains. The parsing functions accept a raw query string with or without a leading "?", or a complete URL. They preserve parameter order and duplicate keys, ignore empty keys, and do not URL-decode values. remove_query_string accepts a complete URL. For example: SELECT query_string_params(url) FROM catalog.crawl_pages_20251201 SELECT remove_query_string(url, ['bar']) FROM catalog.crawl_pages_20251201 The logs crawls and visits tables (catalog.logs_google_crawls) have a virtual `url` column, resolved from `url_hash` after the query runs. It can only be selected, grouped by or counted: to filter, join, sort or transform URLs, join catalog.logs_urls on url_hash.

Playground

POST
item
query required

BigQuery SQL query to execute

max_results

Maximum number of results to return

config
bigquery_billing

Who pays BigQuery for the query. 'botify': Botify runs it, and the data it scans is charged in credits. 'organization': it runs in your organization's own GCP project, configured by Botify, which Google bills directly; a flat fee per query is charged in credits instead of the scan. 'auto': your organization's project when one is configured, else Botify.

Credits

Fixed cost per item requested, plus the data the query scans. Analytical queries are billed on how much data they read, not on how many rows come back, so a narrow filter over a large table can still scan the whole of it. Restricting the columns and the date range you ask for is what keeps this down. A query run in your organization's own cloud project (see bigquery_billing) has its scan billed by your cloud provider instead, and costs a flat fee per query here.

These usage SKUs can be charged on a call.

SKU Credits Description
Tool call 1 per request Charged once per successful item, on top of any usage below.
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.
Query billed to your cloud project 4 per query A flat fee per query run in your organization's own cloud project, in place of the charge on the data it scans.

Schemas

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

Item

object
Properties
query string required

BigQuery SQL query to execute

max_results integer

Maximum number of results to return

Default: 10000

min 1, max 10000

Example
{
  "query": "string",
  "max_results": 10000
}

Configuration

object
Properties
bigquery_billing string

Who pays BigQuery for the query. 'botify': Botify runs it, and the data it scans is charged in credits. 'organization': it runs in your organization's own GCP project, configured by Botify, which Google bills directly; a flat fee per query is charged in credits instead of the scan. 'auto': your organization's project when one is configured, else Botify.

Values: auto botify organization

Default: "auto"

Example
{
  "bigquery_billing": "auto"
}

Response

object
Properties
fields array required

Field definitions with name and type

results array required

Query execution results as list of lists

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

Endpoints

POST http://agents.botify.com/{organization}/{project}/tables_query/process
POST http://agents.botify.com/{organization}/{project}/tables_query/batch_process
POST http://agents.botify.com/{organization}/{project}/tables_query/async_process
POST http://agents.botify.com/{organization}/{project}/tables_query/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_query/process" \
  -H "Authorization: Bearer $BOTIFY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "item": {
    "query": "<query>"
  }
}'

Over MCP

This tool is exposed as the MCP tool tables_query. An MCP client passes organization, project and item as tool arguments. Set up MCP →

Raw metadata