Hex Rate Limits

Overview

Hex's API enforces tight limits on project run triggers (20 per minute, 60 per hour) while leaving read operations like status checks and project listing largely unthrottled. Data teams scheduling batch analytics runs or triggering parameterized notebooks from CI/CD pipelines must carefully manage the hourly cap, since a single pipeline triggering 15 projects can consume a quarter of the hourly budget. Polling run status is free, but triggering runs is the bottleneck that shapes integration architecture.

Rate Limit Reference

Rate Limiter Implementation

class HexRateLimiter {
  private minuteTokens: number = 20;
  private hourlyTokens: number = 60;
  private lastMinuteRefill: number = Date.now();
  private lastHourlyRefill: number = Date.now();
  private queue: Array<{ resolve: () => void }> = [];

  async acquire(): Promise<void> {
    this.refill();
    if (this.minuteTokens >= 1 && this.hourlyTokens >= 1) {
      this.minuteTokens -= 1;
      this.hourlyTokens -= 1;
      return;
    }
    return new Promise(resolve => this.queue.push({ resolve }));
  }

  private refill() {
    const now = Date.now();
    this.minuteTokens = Math.min(20, this.minuteTokens + ((now - this.lastMinuteRefill) / 60_000) * 20);
    this.lastMinuteRefill = now;
    this.hourlyTokens = Math.min(60, this.hourlyTokens + ((now - this.lastHourlyRefill) / 3_600_000) * 60);
    this.lastHourlyRefill = now;
    while (this.minuteTokens >= 1 && this.hourlyTokens >= 1 && this.queue.length) {
      this.minuteTokens -= 1;
      this.hourlyTokens -= 1;
      this.queue.shift()!.resolve();
    }
  }
}

const runLimiter = new HexRateLimiter();

Retry Strategy

async function hexRunWithRetry(
  projectId: string, params: Record<string, any>, maxRetries = 3
): Promise<any> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    await runLimiter.acquire();
    const res = await fetch(`${HEX_BASE}/api/v1/run/${projectId}`, {
      method: "POST", headers,
      body: JSON.stringify({ inputParams: params }),
    });
    if (res.ok) return res.json();
    if (res.status === 429) {
      const delay = 30_000 * Math.pow(2, attempt) + Math.random() * 5000;
      await new Prom

Hex SDK Patterns

Overview

Production patterns for Hex API: typed client, pipeline orchestration, retry logic, and Python integration.

Instructions

Step 1: Run with Retry

async function runWithRetry(client: HexClient, projectId: string, params: Record<string, any>, maxRetries = 2) {
  for (let i = 0; i <= maxRetries; i++) {
    try {
      const { runId } = await client.runProject(projectId, params);
      const result = await pollUntilComplete(client, projectId, runId);
      return result;
    } catch (err: any) {
      if (i === maxRetries || !err.message.includes('429')) throw err;
      await new Promise(r => setTimeout(r, 30000)); // Wait 30s on rate limit
    }
  }
}

Step 2: Python Client (hextoolkit)

# pip install hextoolkit
from hextoolkit import HexAPI

hex_api = HexAPI(token=os.environ['HEX_API_TOKEN'])

# List projects
projects = hex_api.list_projects()

# Run project
run = hex_api.run_project('project-id', input_params={'date': '2025-01-01'})

# Poll for completion
status = hex_api.get_run_status('project-id', run['runId'])

Step 3: Airflow Integration

# Using the hex-inc/airflow-provider-hex package
from airflow_provider_hex.operators.hex import HexRunProjectOperator

run_task = HexRunProjectOperator(
    task_id='run_hex_project',
    project_id='your-project-id',
    input_params={'date': '{{ ds }}'},
    hex_conn_id='hex_default',
    wait_for_completion=True,
    timeout=600,
)

Resources

• Hex API
• Airflow Provider

Next Steps

Apply patterns in hex-core-workflow-a.

Hex Security Basics

Overview

Hex is a collaborative data analytics platform where notebooks query production databases, generate visualizations, and share results across teams. Security concerns center on API token management (read vs run scopes), protecting database connection credentials embedded in Hex projects, and ensuring query results containing sensitive business data are not leaked through logs or exports. A compromised run-scope token can trigger arbitrary queries against connected databases.

API Key Management

function createHexClient(scope: "read" | "run"): { token: string; baseUrl: string } {
  const envVar = scope === "run" ? "HEX_RUN_TOKEN" : "HEX_READ_TOKEN";
  const token = process.env[envVar];
  if (!token) {
    throw new Error(`Missing ${envVar} — store in secrets manager, never in code`);
  }
  // Run tokens can trigger queries — use read tokens for monitoring
  console.log(`Hex client initialized with ${scope} scope (token suffix: ${token.slice(-4)})`);
  return { token, baseUrl: "https://app.hex.tech/api/v1" };
}

Webhook Signature Verification

import crypto from "crypto";
import { Request, Response, NextFunction } from "express";

function verifyHexWebhook(req: Request, res: Response, next: NextFunction): void {
  const signature = req.headers["x-hex-signature"] as string;
  const secret = process.env.HEX_WEBHOOK_SECRET!;
  const expected = crypto.createHmac("sha256", secret).update(req.body).digest("hex");
  if (!signature || !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    res.status(401).send("Invalid signature");
    return;
  }
  next();
}

Input Validation

import { z } from "zod";

const HexRunRequestSchema = z.object({
  project_id: z.string().uuid(),
  input_params: z.record(z.string(), z.unknown()).optional(),
  notify_on_completion: z.boolean().default(false),
  update_cache: z.boolean().default(false),
});

function validateHexRunRequest(data: unknown) {
  return HexRunRequestSchema.parse(data);
}

Data Protection

const HEX_SENSITIVE_FIELDS = ["db_connection_string", "query_results", "api_token", "input_params", "export_url"];

function redactHexLog(record: Record<string, unknown>): Record<string, unknown> {
  const redacted = { ...record };
  for (const field of HEX_SENSITIVE_FIELDS) {
    if (field in redacted) redacted[field] = "[REDACTED]";
  }
  return redacted;
}

Security Checklist

• [ ] API tokens stored in secrets vault, never in code
• [ ] Read-only tokens for monitoring, run tokens for orchestration only

Hex Upgrade & Migration

Overview

Hex API is versioned at /api/v1/. Monitor the Hex changelog for new endpoints and deprecations.

Instructions

Check API Usage

grep -r "app.hex.tech" src/ --include="*.ts" --include="*.py"

Airflow Provider Updates

pip install --upgrade airflow-provider-hex

Resources

• Hex Changelog
• API Reference

Hex Webhooks & Events

Overview

Hex doesn't provide push webhooks. For event-driven integrations, poll run status or build your own notification system around run completions.

Instructions

Run Status Polling with Callback

async function runWithCallback(
  client: HexClient,
  projectId: string,
  params: Record<string, any>,
  onComplete: (result: any) => void,
  onError: (error: Error) => void
) {
  try {
    const { runId } = await client.runProject(projectId, params);
    const poll = async () => {
      const status = await client.getRunStatus(projectId, runId);
      if (status.status === 'COMPLETED') { onComplete(status); return; }
      if (status.status === 'ERRORED' || status.status === 'KILLED') { onError(new Error(status.status)); return; }
      setTimeout(poll, 5000);
    };
    poll();
  } catch (err) { onError(err as Error); }
}

Notify on Completion

runWithCallback(client, 'project-id', { date: '2025-01-01' },
  (result) => {
    // Send Slack notification, email, etc.
    fetch(process.env.SLACK_WEBHOOK_URL!, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ text: `Hex project completed: ${result.runId}` }),
    });
  },
  (error) => console.error('Run failed:', error)
);

Resources

• Hex API