Hex Scheduled Runs & Admin API

Overview

Configure scheduled runs and manage workspace resources via the Hex Admin API. Scheduled runs execute projects on cron-based intervals. The Admin API manages users, groups, and data connections.

Instructions

Step 1: List Project Runs

const TOKEN = process.env.HEX_API_TOKEN!;
const BASE = 'https://app.hex.tech/api/v1';

async function getProjectRuns(projectId: string) {
  const response = await fetch(`${BASE}/project/${projectId}/runs`, {
    headers: { 'Authorization': `Bearer ${TOKEN}` },
  });
  const runs = await response.json();
  for (const run of runs) {
    console.log(`${run.runId}: ${run.status} (${run.startTime} → ${run.endTime || 'running'})`);
  }
  return runs;
}

Step 2: Scheduled Runs (via Hex UI + API Trigger)

Schedules are configured in the Hex UI. For API-based scheduling, use external cron:

// cron-trigger.ts — run via cron job or CI
import cron from 'node-cron';

// Daily at 6 AM UTC
cron.schedule('0 6 * * *', async () => {
  console.log('Triggering daily report...');
  await triggerRun({
    projectId: 'daily-report-project-id',
    inputParams: { date: new Date().toISOString().split('T')[0] },
    updateCache: true,
  });
});

// Weekly on Monday at 9 AM
cron.schedule('0 9 * * 1', async () => {
  await triggerRun({ projectId: 'weekly-summary-project-id' });
});

Step 3: User Management (Admin API)

// List workspace users
async function listUsers() {
  const response = await fetch(`${BASE}/workspace/users`, {
    headers: { 'Authorization': `Bearer ${TOKEN}` },
  });
  return response.json();
}

// List groups
async function listGroups() {
  const response = await fetch(`${BASE}/workspace/groups`, {
    headers: { 'Authorization': `Bearer ${TOKEN}` },
  });
  return response.json();
}

Step 4: Data Connection Management

// List configured data connections
async function listConnections() {
  const response = await fetch(`${BASE}/workspace/connections`, {
    headers: { 'Authorization': `Bearer ${TOKEN}` },
  });
  return response.json();
}

Scheduling Options

Method	Intervals	Plan Required
Hex UI	Hourly, daily, weekly, monthly	Team+
Hex UI (cron)	Any cron expression	Team+
API trigger + external cron	Any schedule	Team+
Airflow/Dagster integration	Any schedule	Team+

Prerequisites

A named data/project owner, approved parameter and destination policy, scoped credential, and safe sandbox project.
Opaque run IDs, idempotency strategy, aggregate assertions, and a cancellation/rollback plan.

Output

Return a workflow receipt with project, run, parameter revision, accepted/quarantined operation counts, idempotency state, aggregate assertion, cancellation result, and rollback reference. Never include SQL, output, or credentials.

Error Handling

Quarantine unknown project, parameter, destination, or response shape. Cancel failed runs and restore prior configuration; do not retry mutations without idempotency or export output to a diagnostic channel.

Examples

project=proj-sandbox-12; run=run-opaque-4; params=r3; accepted=24; quarantined=1; assertions=pass; rollback=workflow-r6 is a controlled execution result.

Resources

Next Steps

For common errors, see hex-common-errors.