Hex Run

Hex Run
Certified
Run a Hex project and wait for completion

Starts the latest published version of a Hex project through the Hex API (https://learn.hex.tech/docs/api/api-reference) and, by default, polls until the run reaches a terminal state. Set wait to false to start the run and return immediately with its ID.

If the task is retried after a worker restart, it reattaches to the run it already started instead of starting a duplicate: the run ID is persisted to the flow's namespace KV store keyed by this task run, and is looked up again on every attempt before deciding whether to call the start endpoint.

With assets.enableAuto set, emits one asset for the Hex project so Hex appears as the terminal consumer of a lineage chain. Hex's API does not report which tables a project reads, so upstream edges are declared with assets.inputs.

yaml
type: io.kestra.plugin.hex.projects.Run

Examples

Run a Hex project and wait for it to complete.

yaml
id: run_hex_project
namespace: company.team

tasks:
  - id: run_dashboard_refresh
    type: io.kestra.plugin.hex.projects.Run
    apiToken: "{{ secret('HEX_API_TOKEN') }}"
    projectId: "00000000-0000-0000-0000-000000000000"

Start a Hex project run with input parameters, without waiting for it to finish.

yaml
id: start_hex_project
namespace: company.team

tasks:
  - id: start_ingestion
    type: io.kestra.plugin.hex.projects.Run
    apiToken: "{{ secret('HEX_API_TOKEN') }}"
    projectId: "00000000-0000-0000-0000-000000000000"
    inputParams:
      run_date: "{{ now() | date('yyyy-MM-dd') }}"
    wait: false

Run a Hex project and record it as the terminal node of a dbt lineage chain.

yaml
id: run_hex_project_with_assets
namespace: company.team

tasks:
  - id: refresh_dashboard
    type: io.kestra.plugin.hex.projects.Run
    apiToken: "{{ secret('HEX_API_TOKEN') }}"
    projectId: "00000000-0000-0000-0000-000000000000"
    assets:
      enableAuto: true
      # Hex reports no upstream tables, so the project's sources are declared here using the
      # database.schema.table ids that dbt and Fivetran emit, which is what joins the graph.
      inputs:
        - id: analytics.marts.fct_orders
          type: io.kestra.plugin.ee.assets.Table
        - id: analytics.marts.dim_customers
          type: io.kestra.plugin.ee.assets.Table

Properties

apiToken *string

Hex API token

Bearer token for the Hex API. Generate one from your Hex workspace's API key settings and store it as a Kestra secret.

projectId *string

Hex project ID

The ID of the Hex project to run.

baseUrl string

Defaulthttps://app.hex.tech/api/v1

Hex API base URL

Base endpoint for all requests. Defaults to https://app.hex.tech/api/v1; override only for a self-hosted Hex region.

inputParams object

Input parameters

Values for the project's input cells, as a map of parameter name to value. Only parameters already declared as input cells in the Hex project can be set this way.

maxDuration string

DefaultPT1H

Maximum wait duration

Upper bound for waiting when wait is true, after which the task fails with a timeout. Default is 1 hour.

pluginDefaultsRef string

Reference (ref) of the pluginDefaults to apply to this task.

pollFrequency string

DefaultPT5S

Poll frequency

Interval between run status checks while waiting for completion. Default is 5 seconds. Keep this conservative: the Hex API allows roughly 30 status requests per minute.

wait booleanstring

Defaulttrue

Wait for completion

When true (default), poll the run until it reaches a terminal state. When false, start the run (or reattach to one already in flight) and return immediately with its current status.

Outputs

elapsedTime string

Formatduration

Elapsed time

Duration of the run, taken from Hex's reported elapsed time or, if absent, computed from startTime/endTime.

endTime string

Formatdate-time

End time

When the run reached a terminal state. Null while the run has not completed yet.

projectVersion string

Project version

Published version of the Hex project that was run.

runId string

Hex run ID

Identifier of the Hex project run.

runUrl string

Run URL

Link to view this run in the Hex UI.

startTime string

Formatdate-time

Start time

When the run started executing.

status string

Run status

Status reported by Hex, e.g. PENDING, RUNNING, COMPLETED, ERRORED, KILLED, or UNABLE_TO_ALLOCATE_KERNEL. When wait is false, this is a snapshot taken right after the run was started or reattached, so it is typically not yet terminal.