# Hex

> Run Hex notebooks programmatically with parameters and check run status.

Source: https://cotera.co/docs/reference/tools/individual-tools/hex

---

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

***

## Authentication

To authenticate, you'll need a Hex workspace token. Learn how to generate one in the [Hex API documentation](https://learn.hex.tech/docs/api/api-overview).

**Required Scopes:**

* `projects:all` - Access to run and manage projects

***

## 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:**

```json
{
  "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:**

```json
{
  "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