Skip to main content

Hex API

Programmatically run Hex projects with the API.

The Hex public API provides a way to trigger runs of published Hex projects. If you are looking to trigger these runs from an orchestrator, check out the Hex managed Airflow and Dagster integrations, or the Prefect and Shipyard integrations. For path parameters and schema of specific endpoints, view the API reference.

tip

This feature is only available for workspaces on Teams or Enterprise plans.

Authentication

API Requests are authenticated using Oauth 2.0 Bearer Tokens in the header of the HTTP request. The token is always bound to a single Hex user's account and requests are executed as that Hex user, meaning the user can only execute requests against projects that are in line with the current permissions for that project.

Token creation

Personal access tokens can be created from the API keys section of the User settings page.

A new token can be created by selecting the New Token button, then inputting a description and an expiration time frame. An existing token can be regenerated at any time by selecting the three-dot menu to the right of the token, and selecting Regenerate.

danger

Regenerating a personal access token will generate a new value for the token and immediately revoke the existing token.

Token expiration

Admins can specify the maximum expiration time for tokens to be 7, 30, 60, 90, or 120 days. When creating a token, users can specify a time to live that is equal to or shorter than the maximum expiration time. Users will receive an email notification 72 hours before and 24 hours before a token expires, warning them that the token will be expiring soon. Tokens can be manually revoked by clicking the three-dot menu to the right of the token, and selecting Revoke. Once a token is revoked or expired, the token can never again be used to authenticate requests.

Using the API

The Hex API allows users to programmatically run published Hex projects. This makes it simple to run projects with specific inputs, and allows for automation of workflows that update cached query results and the cached state of an app. The full reference docs for the API can be found here.

The below examples use the requests package to run the API, though the API can be invoked by many other methods (e.g. running a cURL command).

Setup needed for the API

To use the API correctly, first run some setup code. Ensure that you replace values for your specific use-case.

  • Base URL: For most Hex users, this will be https://app.hex.tech/api/v1. Single-tenant app users should replace the app.hex.tech part of this URL with the URL they use to access Hex (e.g. atreides.hex.tech).
  • Project ID: The project ID can be found by visiting the project you wish to run, and copying it from the URL — the ID is the part of the URL after the /hex/. Additionally, the project ID can be found in the Variables view of the sidebar.
  • Token: See the above section on token creation. Consider using a secret to store this more securely.

Example

import requests

# Single tenant users will need to replace this with their Hex URL
BASE_URL = 'https://app.hex.tech/api/v1'

# Replace this with the project ID
PROJECT_ID = '5a8591dd-4039-49df-9202-96385ba3eff8'

# Replace this with your token
TOKEN = '5bbf1c8b1989d6657d5c'

Run a published project with default inputs

This API call uses the RunProject endpoint to run a published project with its default inputs. It does not update the cache for this project (see below example)

Example

response = requests.post(
url=f"{BASE_URL}/project/{PROJECT_ID}/run",
headers={"Authorization" : f"Bearer {TOKEN}"}
)

The response from this request will contain a runUrl which will display the results of the project run as a Snapshot, viewable by any user who has at least view access to the project.

Run a published project with custom inputs

The RunProject endpoint contains an optional inputParams body parameter that allows users to specify the values for Input parameters to be used in the project run.

Example

inputs = {
"inputParams": {
"user_name": "j_doe",
"team": "finance",
"id": 1234567890
}
}

response = requests.post(
url=f"{BASE_URL}/project/{PROJECT_ID}/run",
json=inputs,
headers={"Authorization" : f"Bearer {TOKEN}"}
)

Update the cached state and query cache of a published project

When updateCache is set to true in a RunProject request, the project run can refresh the cached state displayed for users when the published app is opened, as well as the cached results of SQL queries.

In order to update the cached state of the published app, cache default state must be enabled. If inputParams are included in the request when updateCache is set to true, the Input parameter values will be ignored. This is because updating the published app’s cache state requires the default Input parameter values to be used.

In order for a query to execute and update cached results, query caching must be enabled, and the On scheduled run configuration option must also be enabled. If query caching is enabled and the on scheduled run option is disabled, the project run will use cached query results, if available.

Example


inputs = {
"updateCache": "true"
}

response = requests.post(
url=f"{BASE_URL}/project/{PROJECT_ID}/run",
json=inputs,
headers={"Authorization" : f"Bearer {TOKEN}"}
)

Cancel active runs for a project

Project runs can be cancelled using the CancelRun endpoint. This can be especially useful if project runs triggered by the API are contributing to database performance degradation, or your user is running into the kernel limit. The GetProjectRuns endpoint can be used in conjunction with this in order to easily cancel all project runs.

Example

# Get all runs for project
response = requests.get(
url=f"{BASE_URL}/project/{PROJECT_ID}/runs",
params={"limit": 25, "statusFilter": "RUNNING"},
headers={"Authorization" : f"Bearer {TOKEN}"}
)
response = response.json()

# Iterate through runs and cancel them
for run in response["runs"]:
run_id = run["runId"]
requests.delete(
url=f"{BASE_URL}/project/{PROJECT_ID}/run/{run_id}",
headers={"Authorization" : f"Bearer {TOKEN}"}
)

Kernel and rate limits

Users are limited to 60 API requests per minute. If a user exceeds 60 requests in a minute, subsequent requests will be denied and return a 429 status until the rate limit is reset, 60 seconds after the first request. Request response headers contain metadata about the remaining number of requests allowed, and when the rate limit will be reset.

Users are also limited to 25 concurrently running kernels between projects opened in the Hex UI and project runs triggered via the API. Each RunProject request will use a single kernel until the project run completes. Once 25 kernels are running, subsequent RunProject requests and will have a PENDING status while they wait for a kernel to become available. In addition to this, projects opened in the UI that do not already have a running kernel will show a pending state. Cancelling a project run using the CancelRun endpoint will also stop the kernel.

Troubleshooting

401 Unauthorized

A 401 status code indicates that Hex was unable to authenticate the request. Make sure that a token is being included in the header of your request. If you are including a token in the header of the request, double-check that the token has not expires and consider regenerating the token or creating a new token.

404 Not found

A 404 status code indicates that Hex was unable to find the resource referenced. This could mean that the project ID or run ID included in the request are not accurate, or that your user does not have permission for the requested resource. Double-check that the user an access the Hex project in the UI.

429 Too many requests

A 429 status code indicates that you have hit the request rate limit. See the section on rate limiting above for more information.

500 Internal server error

A 500 status code indicates an error with the Hex application. Please contact Hex support for help troubleshooting.