---

name: hex-performance-tuning description: 'Optimize Hex API performance with caching, batching, and connection pooling.

Use when experiencing slow API responses, implementing caching strategies,

or optimizing request throughput for Hex integrations.

Trigger with phrases like "hex performance", "optimize hex",

"hex latency", "hex caching", "hex slow", "hex batch".

' allowed-tools: Read, Write, Edit version: 1.6.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:

• saas
• hex
• data
• analytics compatibility: Designed for Claude Code

---

Hex Performance Tuning

Latency Benchmarks

Operation	Typical Duration
ListProjects	200-500ms
RunProject (trigger)	500ms-2s
Project execution	10s-30min (depends on queries)
GetRunStatus (poll)	100-300ms

Instructions

Cache Project Lists

import { LRUCache } from 'lru-cache';
const projectCache = new LRUCache<string, any>({ max: 50, ttl: 300000 }); // 5 min

async function getCachedProjects(client: HexClient) {
  const cached = projectCache.get('projects');
  if (cached) return cached;
  const projects = await client.listProjects();
  projectCache.set('projects', projects);
  return projects;
}

Parallel Independent Runs

// Run independent projects in parallel (respecting rate limits)
async function parallelRuns(client: HexClient, configs: Array<{ id: string; params: any }>) {
  return Promise.allSettled(
    configs.map(c => runWithRetry(client, c.id, c.params))
  );
}

Optimize Poll Interval

// Adaptive polling: start fast, slow down
async function adaptivePoll(client: HexClient, projectId: string, runId: string) {
  let interval = 2000; // Start at 2s
  while (true) {
    const status = await client.getRunStatus(projectId, runId);
    if (['COMPLETED', 'ERRORED', 'KILLED'].includes(status.status)) return status;
    await new Promise(r => setTimeout(r, interval));
    interval = Math.min(interval * 1.5, 30000); // Max 30s
  }
}

Overview

Tune run latency and throughput using safe sandbox projects and aggregate metrics. A gain is invalid if it expands data scope, compromises output correctness, exceeds quota, or makes rollback impossible.

Prerequisites

• Baseline latency/run metrics, safe fixture revision, approved error budget, and a rollback revision for cache, concurrency, parameters, and retry policy.

Output

Return a tuning receipt with baseline/canary percentile bands, cache/concurrency/parameter revisions, quota/error outcomes, aggregate assertion, owner approval, and rollback reference. Use aggregates only.

Error Handling

Roll back for quota saturation, increased errors, changed output assertion, access drift, or duplicate runs. Do not raise concurrency or cache duration to hide a failing dependency.

Examples

env=sandbox; p95=420ms->310ms; concurrency=2; cache=r4; quota=within-budget; assertions=pass; rollback=perf-r3 documents a safe canary.

Resources

• Hex API