Hex

Authentication Type: API Key
Description: Run Hex notebooks programmatically with parameters and check run status.

Runs

Operations for Hex notebook runs.

Run Notebook

Starts a new Hex notebook run with optional input parameters.

Operation Type: Mutation (Write)

Parameters:

• baseUrl string (required): The base URL for the Hex API (e.g., https://app.hex.tech/api/v1)
• projectId string (required): The ID of the Hex project containing the notebook to run
• inputParamsJson string (nullable): JSON string of input parameters to pass to the notebook. Use null if no parameters needed
• updatePublishedResults boolean (nullable): Whether to update published results after the run completes. Use null for default behavior
• useCachedSqlResults boolean (nullable): Whether to use cached SQL results if available. Use null for default behavior

Returns:

• runId string: The ID of the created notebook run
• status string: The initial status of the run
• runUrl string (nullable): URL to view the run in Hex

Example Usage:

{
  "baseUrl": "https://app.hex.tech/api/v1",
  "projectId": "01234567-89ab-cdef-0123-456789abcdef",
  "inputParamsJson": "{\"start_date\": \"2024-01-01\", \"end_date\": \"2024-01-31\", \"region\": \"US\"}",
  "updatePublishedResults": true,
  "useCachedSqlResults": false
}

Get Run Status

Checks the status of a Hex notebook run and retrieves results if completed.

Operation Type: Query (Read)

Parameters:

• baseUrl string (required): The base URL for the Hex API
• runId string (required): The ID of the notebook run to check

Returns:

• runId string: The ID of the notebook run
• status string: The current status of the run
• result any (nullable): The result data if the run completed successfully
• error string (nullable): Error message if the run failed
• progress number (nullable): Progress percentage (0-100) if available
• startTime string (nullable): ISO timestamp when the run started
• endTime string (nullable): ISO timestamp when the run completed

Example Usage:

{
  "baseUrl": "https://app.hex.tech/api/v1",
  "runId": "run_01234567-89ab-cdef-0123-456789abcdef"
}

Common Use Cases

Automated Reporting:

• Schedule regular execution of analytical notebooks for daily, weekly, or monthly reports
• Pass dynamic date ranges and filters to generate up-to-date business intelligence
• Update published dashboards with fresh data from automated notebook runs

Data Pipeline Integration:

• Trigger notebook execution as part of larger data processing workflows
• Use cached SQL results for faster execution when underlying data hasn't changed
• Chain multiple notebook runs by checking completion status before proceeding

Parameter-Driven Analysis:

• Run the same notebook with different parameters for A/B testing scenarios
• Generate customized reports for different regions, time periods, or customer segments
• Execute exploratory analysis with varying input parameters for hypothesis testing

Monitoring and Alerting:

• Check run status programmatically to detect failed executions
• Monitor progress of long-running analytical processes
• Set up alerts based on notebook run results or completion status