baselight

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object"
}

Search the catalog for datasets using a text query and filters. Datasets in Baselight have the following format: @username.dataset. Datasets can be public or private — you can search and use all public datasets as well as the user's private datasets. This is typically the first step in the discovery workflow.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "The search query string, used for semantic search"
    },
    "category": {
      "description": "The dataset category to filter by",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "Academic Research",
          "Astronomy and Space Sciences",
          "Crypto and Blockchain",
          "Demographics and Population Studies",
          "Ecommerce and Consumer Trends",
          "Environmental and Climate Sciences",
          "Finance and Economics",
          "Healthcare",
          "Media and Entertainment",
          "Politics and Governance",
          "Prediction Markets",
          "Sports",
          "Technology and IT",
          "Transportation and Logistics"
        ]
      }
    },
    "limit": {
      "default": 10,
      "description": "Maximum number of datasets to return (1-20, default 10)",
      "type": "number",
      "minimum": 1,
      "maximum": 20
    }
  },
  "required": [
    "query"
  ]
}

Search for tables using a text query and filters. Tables in Baselight have the following format: @username.dataset.table. Tables are grouped into datasets which can be public or private — you can search and use all public datasets as well as the user's private datasets. Search for tables directly when you are unable to find relevant datasets.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "The search query string, used for semantic search"
    },
    "category": {
      "description": "The dataset category to filter by",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "Academic Research",
          "Astronomy and Space Sciences",
          "Crypto and Blockchain",
          "Demographics and Population Studies",
          "Ecommerce and Consumer Trends",
          "Environmental and Climate Sciences",
          "Finance and Economics",
          "Healthcare",
          "Media and Entertainment",
          "Politics and Governance",
          "Prediction Markets",
          "Sports",
          "Technology and IT",
          "Transportation and Logistics"
        ]
      }
    },
    "limit": {
      "default": 10,
      "description": "Maximum number of tables to return (1-20, default 10)",
      "type": "number",
      "minimum": 1,
      "maximum": 20
    }
  },
  "required": [
    "query"
  ]
}

Retrieve detailed schema and metadata for a specific dataset using Baselight format @username.dataset. Use this after discovering datasets to understand their structure before querying. Tables within datasets follow the format @username.dataset.table (always double-quoted identifiers in SQL).

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "The identifier of the dataset to inspect, should be something like @user.dataset"
    }
  },
  "required": [
    "id"
  ]
}

Retrieve a paginated list of tables from a specific dataset using Baselight format @username.dataset. Use this tool to browse datasets with many tables or to search for specific tables within a dataset. Each page returns up to 100 tables with metadata.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "The identifier of the dataset to browse, should be something like @user.dataset"
    },
    "query": {
      "default": "",
      "description": "Optional text search query to filter tables by name or title. If omitted, returns all tables.",
      "type": "string"
    },
    "page": {
      "description": "Page number to retrieve (starts at 1). Each page contains up to 100 tables.",
      "default": 1,
      "type": "number",
      "minimum": 1
    }
  },
  "required": [
    "id"
  ]
}

Retrieve detailed schema and metadata for a specific table using Baselight format @username.dataset.table. Use this to understand table structure, column types, and constraints before writing SQL queries. Tables must be referenced in SQL with double quotes.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "The full identifier of the table to inspect, should be something like @user.dataset.table"
    }
  },
  "required": [
    "id"
  ]
}

Retrieve detailed information about a Baselight user including their profile bio, website, and public datasets. Use this to understand who owns datasets you're interested in.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "username": {
      "type": "string",
      "minLength": 1,
      "description": "The username of the user to inspect"
    }
  },
  "required": [
    "username"
  ]
}

Execute a SQL query on Baselight and wait for results (up to 1 minute). The query executes and returns the first 100 rows upon completion, or info about a pending query that needs more time. Use DuckDB syntax only, table format "@username.dataset.table" (double-quoted), SELECT queries only (no DDL/DML), no semicolon terminators, use LIMIT not TOP. If query is still PENDING, use `sdk-get-results` to continue polling. If totalResults > returned rows, use `sdk-get-results` with offset to paginate.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "sql": {
      "type": "string",
      "description": "The SQL query to execute. table identifiers should be wrapped in double quotes, like \"@user.dataset.table\". Only SELECT queries are allowed."
    }
  },
  "required": [
    "sql"
  ]
}

Retrieve results from a previously executed SDK job using the resultId from `sdk-query-execute`. If the query is complete, returns results immediately. If still pending, polls for up to 1 more minute. Use this after `sdk-query-execute` returns PENDING status.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string",
      "description": "The result ID of the executed query (from `sdk-query-execute`)."
    },
    "limit": {
      "default": 100,
      "description": "Number of rows to return per page (max 100). Default is 100.",
      "type": "number",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "default": 0,
      "description": "Row offset for pagination. Use to fetch subsequent pages (e.g., offset=100 for page 2).",
      "type": "number",
      "minimum": 0
    }
  },
  "required": [
    "jobId"
  ]
}