Smart Columns

Use {{column_name}} in prompts, URLs, request bodies, and run conditions to reference other columns in the same row. When the smart column runs, each {{...}} placeholder is replaced with the actual value from that row.

What is the capital of {{country}}?
Reply with ONLY the city name.

{
  "contents": [{
    "parts": [{
      "text": "Classify {{company}} ({{website}}) by industry. One word."
    }]
  }]
}

Every smart column has a kind that determines what it does when processing a row. There are 5 kinds:

Add a smart column that processes data per row. AI columns run prompts, HTTP columns call APIs, formula columns compute values, integration columns push data, lookup columns join across tables.

{
  "tool": "hypertab_add_smart_column",
  "arguments": {
    "table": "leads",
    "name": "industry",
    "type": "text",
    "kind": "ai",
    "config": {
      "prompt": "Classify {{company}} by industry. One word."
    },
    "rate_limit": "moderate",
    "auto_run": true
  }
}

Call the Gemini API per row to find the capital of each country. The prompt uses {{country}} to inject the row value.

{
  "tool": "hypertab_add_smart_column",
  "arguments": {
    "table": "countries",
    "name": "capital",
    "type": "text",
    "kind": "http",
    "config": {
      "url": "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=YOUR_KEY",
      "method": "POST",
      "headers": {
        "Content-Type": "application/json"
      },
      "body": {
        "contents": [{
          "parts": [{
            "text": "What is the capital of {{country}}? Reply with ONLY the city name."
          }]
        }],
        "generationConfig": {
          "temperature": 0
        }
      },
      "extract": "candidates[0].content.parts[0].text",
      "run_condition": "{{country}} IS NOT EMPTY"
    },
    "rate_limit": "conservative"
  }
}

Call the OpenAI API per row to summarize a company. Uses {{company}} and {{website}} template variables.

{
  "tool": "hypertab_add_smart_column",
  "arguments": {
    "table": "leads",
    "name": "summary",
    "type": "text",
    "kind": "http",
    "config": {
      "url": "https://api.openai.com/v1/chat/completions",
      "method": "POST",
      "headers": {
        "Content-Type": "application/json",
        "Authorization": "Bearer sk-YOUR_OPENAI_KEY"
      },
      "body": {
        "model": "gpt-4o-mini",
        "messages": [
          {
            "role": "user",
            "content": "Summarize {{company}} ({{website}}) in one sentence."
          }
        ],
        "max_tokens": 100
      },
      "extract": "choices[0].message.content"
    },
    "rate_limit": "moderate"
  }
}

AI columns use hypertab's built-in AI processing. No external API key needed -- just write a prompt with template variables and choose a model. The result is written back to the cell.

{
  "tool": "hypertab_add_smart_column",
  "arguments": {
    "table": "support_tickets",
    "name": "sentiment",
    "type": "text",
    "kind": "ai",
    "config": {
      "prompt": "Classify the sentiment of this support ticket:\n\n{{message}}\n\nReply with exactly one word: positive, negative, or neutral",
      "model": "claude-haiku-4-20250414",
      "max_tokens": 10,
      "temperature": 0
    },
    "rate_limit": "moderate",
    "auto_run": true
  }
}

Formula columns compute a value from other columns in the same row. No external API calls, no rate limiting. The expression is evaluated locally for each row.

{
  "tool": "hypertab_add_smart_column",
  "arguments": {
    "table": "orders",
    "name": "total",
    "type": "number",
    "kind": "formula",
    "config": {
      "expression": "price * quantity"
    }
  }
}

Integration columns push row data to external services. Each row triggers an outbound request to the configured target. Useful for syncing data to Slack, webhooks, CRMs, or any HTTP endpoint.

{
  "tool": "hypertab_add_smart_column",
  "arguments": {
    "table": "alerts",
    "name": "slack_notify",
    "type": "text",
    "kind": "integration",
    "config": {
      "target": "slack",
      "url": "https://hooks.slack.com/services/T00/B00/xxx",
      "method": "POST",
      "body": {
        "text": "New alert: {{title}} (severity: {{severity}})"
      }
    },
    "rate_limit": "conservative",
    "auto_run": true
  }
}

Lookup columns perform a cross-table VLOOKUP. For each row, they find a matching row in another table and return a value from it. No external API calls, no rate limiting.

{
  "tool": "hypertab_add_smart_column",
  "arguments": {
    "table": "orders",
    "name": "customer_company",
    "type": "text",
    "kind": "lookup",
    "config": {
      "source_table": "customers",
      "match_column": "customer_id",
      "return_column": "company_name"
    }
  }
}

Run conditions let you skip rows that don't have the required data. Add a run_condition to any smart column's config. Rows that don't match the condition are marked as "skipped" instead of "error".

Update the configuration of a smart column after creation. Change the AI prompt, HTTP URL, formula expression, rate limit preset, or auto-run setting. Only provided fields are updated; omitted fields are left unchanged.

{
  "tool": "hypertab_update_column_config",
  "arguments": {
    "table": "leads",
    "column": "sentiment",
    "config": {
      "prompt": "Classify sentiment as: very_positive, positive, neutral, negative, very_negative\n\n{{message}}"
    }
  }
}

Trigger smart column processing for all rows or specific rows. Creates a column run and enqueues cells for batch processing. Rate limits are enforced per column config.

{
  "tool": "hypertab_run_column",
  "arguments": {
    "table": "countries",
    "column": "capital"
  }
}

Check the progress of a smart column run. Shows total rows, processed count, error count, and completion status. Use the run_id returned by hypertab_run_column.

{
  "tool": "hypertab_get_column_run_status",
  "arguments": {
    "run_id": "run_abc123"
  }
}

Get per-cell execution states for a smart column. Each cell in a smart column has its own execution state tracking. Filter by status to find failures or pending cells.

{
  "tool": "hypertab_get_cell_states",
  "arguments": {
    "table": "countries",
    "column": "capital",
    "status": "error"
  }
}

Retry all failed cells in a smart column. Creates a new column run for just the cells with "error" status, re-enqueuing them for processing.

{
  "tool": "hypertab_retry_failed_cells",
  "arguments": {
    "table": "countries",
    "column": "capital"
  }
}

Every AI and HTTP smart column stores a structured JSON response with metadata alongside the extracted value. Click any completed cell in the UI to open the Cell Details Panel showing all response fields with the ability to add any field as a new column.

Get the full response metadata for a specific cell.

curl /api/tables/countries/rows/ROW_ID/cells/capital \
  -H "Authorization: Bearer ht_sk_..."

AI columns can return structured JSON instead of plain text. Define an output_schema in the column config, and the AI will return a JSON object matching that schema. The cell shows the first field value with aJSON badge. Click the cell to expand all fields.

{
  "tool": "hypertab_add_smart_column",
  "arguments": {
    "table": "my_leads",
    "name": "research",
    "type": "json",
    "kind": "ai",
    "config": {
      "provider_id": "prv_...",
      "model": "gemini-2.5-flash",
      "prompt": "Research {{company}} ({{website}}).",
      "output_schema": {
        "type": "object",
        "properties": {
          "industry": { "type": "string" },
          "employee_count": { "type": "number" },
          "hq_city": { "type": "string" },
          "revenue": { "type": "string" }
        },
        "required": ["industry", "employee_count", "hq_city", "revenue"]
      },
      "run_condition": "{{company}} IS NOT EMPTY"
    }
  }
}

HTTP columns support Clay-level configuration: query parameters, retries, timeouts, multi-extract, saved API accounts, and more.

{
  "config": {
    "url": "https://api.github.com/orgs/{{company}}",
    "method": "GET",
    "account_id": "acct_...",
    "extracts": {
      "repos": "public_repos",
      "followers": "followers",
      "blog": "blog",
      "location": "location"
    },
    "timeout_ms": 10000,
    "retry_on_failure": true,
    "max_retries": 2,
    "retry_status_codes": [429, 500, 502, 503]
  }
}

Save named API accounts with auth headers. Use account_id in HTTP column config to auto-inject headers without pasting API keys every time.

{
  "tool": "hypertab_save_api_account",
  "arguments": {
    "name": "My GitHub API",
    "service": "github",
    "auth_type": "bearer",
    "token": "ghp_your_token_here",
    "base_url": "https://api.github.com",
    "description": "GitHub production API key"
  }
}

Manage accounts: hypertab_list_api_accounts, hypertab_update_api_account, hypertab_delete_api_account. Or use Settings → API Accounts in the UI.

A table can contain multiple tabs (pipeline stages). Each tab has its own columns and rows. Linked tabs auto-sync data from a parent tab based on filter conditions. JSON fields from smart columns are expanded into real columns on the linked tab.

{
  "tool": "hypertab_create_tab",
  "arguments": {
    "table": "my_leads",
    "name": "qualified_leads",
    "source_column": "research",
    "filter": {
      "research.employee_count": { "gte": 500 }
    },
    "description": "Leads with 500+ employees"
  }
}

// Creates a new tab that:
// 1. Inherits parent columns (company, website)
// 2. Expands JSON fields from 'research' column (industry, employee_count, hq_city, revenue)
// 3. Only syncs rows where employee_count >= 500

Set auto_run: true in a smart column's config to automatically process new rows when they're inserted. The column run triggers immediately afterhypertab_insert_rows completes.

{
  "tool": "hypertab_update_column_config",
  "arguments": {
    "table": "my_leads",
    "column": "research",
    "config": { "auto_run": true }
  }
}

// Now when you insert rows:
// hypertab_insert_rows({ table: "my_leads", rows: [...] })
// → 'research' column automatically starts processing the new rows