Hex | Sim Docs

Use Hex to run analytics projects, inspect results and run status, and manage workspace collections and groups. Connect with a Hex API token.

Use the block

Run projects, check run status, manage collections and groups (including membership and deactivating users), list users, and view data connections. Requires a Hex API token.

Actions

Hex Cancel Run

Cancel an active Hex project run.

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	Hex API token (Personal or Workspace)
`projectId`	string	Yes	The UUID of the Hex project
`runId`	string	Yes	The UUID of the run to cancel

Output

Parameter	Type	Description
`success`	boolean	Whether the run was successfully cancelled
`projectId`	string	Project UUID
`runId`	string	Run UUID that was cancelled

Hex Create Collection

Create a new collection in the Hex workspace to organize projects.

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	Hex API token (Personal or Workspace)
`name`	string	Yes	Name for the new collection
`description`	string	No	Optional description for the collection

Output

Parameter	Type	Description
`id`	string	Newly created collection UUID
`name`	string	Collection name
`description`	string	Collection description
`creator`	object	Collection creator
↳ `email`	string	Creator email
↳ `id`	string	Creator UUID

Hex Create Group

Create a new group in the Hex workspace, optionally with initial members.

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	Hex API token (Personal or Workspace)
`name`	string	Yes	Name for the new group
`memberUserIds`	json	No	JSON array of user UUIDs to add as initial group members (e.g., ["uuid1", "uuid2"])

Output

Parameter	Type	Description
`id`	string	Newly created group UUID
`name`	string	Group name
`createdAt`	string	Creation timestamp

Hex Deactivate User

Deactivate a user in the Hex workspace.

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	Hex API token (Personal or Workspace)
`userId`	string	Yes	The UUID of the user to deactivate

Output

Parameter	Type	Description
`success`	boolean	Whether the user was successfully deactivated
`userId`	string	User UUID that was deactivated

Hex Delete Group

Delete a group from the Hex workspace.

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	Hex API token (Personal or Workspace)
`groupId`	string	Yes	The UUID of the group to delete

Output

Parameter	Type	Description
`success`	boolean	Whether the group was successfully deleted
`groupId`	string	Group UUID that was deleted

Hex Get Collection

Retrieve details for a specific Hex collection by its ID.

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	Hex API token (Personal or Workspace)
`collectionId`	string	Yes	The UUID of the collection

Output

Parameter	Type	Description
`id`	string	Collection UUID
`name`	string	Collection name
`description`	string	Collection description
`creator`	object	Collection creator
↳ `email`	string	Creator email
↳ `id`	string	Creator UUID

Hex Get Data Connection

Retrieve details for a specific data connection including type, description, and configuration flags.

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	Hex API token (Personal or Workspace)
`dataConnectionId`	string	Yes	The UUID of the data connection

Output

Parameter	Type	Description
`id`	string	Connection UUID
`name`	string	Connection name
`type`	string	Connection type (e.g., snowflake, postgres, bigquery)
`description`	string	Connection description
`connectViaSsh`	boolean	Whether SSH tunneling is enabled
`includeMagic`	boolean	Whether Magic AI features are enabled
`allowWritebackCells`	boolean	Whether writeback cells are allowed

Hex Get Group

Retrieve details for a specific Hex group.

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	Hex API token (Personal or Workspace)
`groupId`	string	Yes	The UUID of the group

Output

Parameter	Type	Description
`id`	string	Group UUID
`name`	string	Group name
`createdAt`	string	Creation timestamp

Hex Get Project

Get metadata and details for a specific Hex project by its ID.

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	Hex API token (Personal or Workspace)
`projectId`	string	Yes	The UUID of the Hex project

Output

Parameter	Type	Description
`id`	string	Project UUID
`title`	string	Project title
`description`	string	Project description
`status`	object	Project status
↳ `name`	string	Status name (e.g., PUBLISHED, DRAFT)
`type`	string	Project type (PROJECT or COMPONENT)
`creator`	object	Project creator
↳ `email`	string	Creator email
`owner`	object	Project owner
↳ `email`	string	Owner email
`categories`	array	Project categories
↳ `name`	string	Category name
↳ `description`	string	Category description
`lastEditedAt`	string	ISO 8601 last edited timestamp
`lastPublishedAt`	string	ISO 8601 last published timestamp
`createdAt`	string	ISO 8601 creation timestamp
`archivedAt`	string	ISO 8601 archived timestamp
`trashedAt`	string	ISO 8601 trashed timestamp

Hex Get Project Runs

Retrieve API-triggered runs for a Hex project with optional filtering by status and pagination.

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	Hex API token (Personal or Workspace)
`projectId`	string	Yes	The UUID of the Hex project
`limit`	number	No	Maximum number of runs to return (1-100, default: 25)
`offset`	number	No	Offset for paginated results (default: 0)
`statusFilter`	string	No	Filter by run status: PENDING, RUNNING, ERRORED, COMPLETED, KILLED, UNABLE_TO_ALLOCATE_KERNEL
`runTriggerFilter`	string	No	Filter by how the run was triggered: ALL, API, SCHEDULED, or APP_REFRESH

Output

Parameter	Type	Description
`runs`	array	List of project runs
↳ `projectId`	string	Project UUID
↳ `runId`	string	Run UUID
↳ `runUrl`	string	URL to view the run
↳ `status`	string	Run status (PENDING, RUNNING, COMPLETED, ERRORED, KILLED, UNABLE_TO_ALLOCATE_KERNEL)
↳ `startTime`	string	Run start time
↳ `endTime`	string	Run end time
↳ `elapsedTime`	number	Elapsed time in seconds
↳ `traceId`	string	Trace ID
↳ `projectVersion`	number	Project version number
`total`	number	Total number of runs returned
`traceId`	string	Top-level trace ID
`nextPage`	string	Cursor for the next page of runs
`previousPage`	string	Cursor for the previous page of runs

Hex Get Queried Tables

Return the warehouse tables queried by a Hex project, including data connection and table names.

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	Hex API token (Personal or Workspace)
`projectId`	string	Yes	The UUID of the Hex project
`limit`	number	No	Maximum number of tables to return (1-100)

Output

Parameter	Type	Description
`tables`	array	List of warehouse tables queried by the project
↳ `dataConnectionId`	string	Data connection UUID
↳ `dataConnectionName`	string	Data connection name
↳ `tableName`	string	Table name
`total`	number	Total number of tables returned

Hex Get Run Status

Check the status of a Hex project run by its run ID.

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	Hex API token (Personal or Workspace)
`projectId`	string	Yes	The UUID of the Hex project
`runId`	string	Yes	The UUID of the run to check

Output

Parameter	Type	Description
`projectId`	string	Project UUID
`runId`	string	Run UUID
`runUrl`	string	URL to view the run
`status`	string	Run status (PENDING, RUNNING, COMPLETED, ERRORED, KILLED, UNABLE_TO_ALLOCATE_KERNEL)
`startTime`	string	ISO 8601 run start time
`endTime`	string	ISO 8601 run end time
`elapsedTime`	number	Elapsed time in seconds
`traceId`	string	Trace ID for debugging
`projectVersion`	number	Project version number

Hex List Collections

List all collections in the Hex workspace.

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	Hex API token (Personal or Workspace)
`limit`	number	No	Maximum number of collections to return (1-500, default: 25)
`sortBy`	string	No	Sort by field: NAME
`after`	string	No	Cursor to fetch the page of results after this value
`before`	string	No	Cursor to fetch the page of results before this value

Output

Parameter	Type	Description
`collections`	array	List of collections
↳ `id`	string	Collection UUID
↳ `name`	string	Collection name
↳ `description`	string	Collection description
↳ `creator`	object	Collection creator
↳ `email`	string	Creator email
↳ `id`	string	Creator UUID
`total`	number	Total number of collections returned
`after`	string	Cursor for the next page of results
`before`	string	Cursor for the previous page of results

Hex List Data Connections

List all data connections in the Hex workspace (e.g., Snowflake, PostgreSQL, BigQuery).

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	Hex API token (Personal or Workspace)
`limit`	number	No	Maximum number of connections to return (1-500, default: 25)
`sortBy`	string	No	Sort by field: CREATED_AT or NAME
`sortDirection`	string	No	Sort direction: ASC or DESC
`after`	string	No	Cursor to fetch the page of results after this value
`before`	string	No	Cursor to fetch the page of results before this value

Output

Parameter	Type	Description
`connections`	array	List of data connections
↳ `id`	string	Connection UUID
↳ `name`	string	Connection name
↳ `type`	string	Connection type (e.g., athena, bigquery, databricks, postgres, redshift, snowflake)
↳ `description`	string	Connection description
↳ `connectViaSsh`	boolean	Whether SSH tunneling is enabled
↳ `includeMagic`	boolean	Whether Magic AI features are enabled
↳ `allowWritebackCells`	boolean	Whether writeback cells are allowed
`total`	number	Total number of connections returned
`after`	string	Cursor for the next page of results
`before`	string	Cursor for the previous page of results

Hex List Groups

List all groups in the Hex workspace with optional sorting.

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	Hex API token (Personal or Workspace)
`limit`	number	No	Maximum number of groups to return (1-500, default: 25)
`sortBy`	string	No	Sort by field: CREATED_AT or NAME
`sortDirection`	string	No	Sort direction: ASC or DESC
`after`	string	No	Cursor to fetch the page of results after this value
`before`	string	No	Cursor to fetch the page of results before this value

Output

Parameter	Type	Description
`groups`	array	List of workspace groups
↳ `id`	string	Group UUID
↳ `name`	string	Group name
↳ `createdAt`	string	Creation timestamp
`total`	number	Total number of groups returned
`after`	string	Cursor for the next page of results
`before`	string	Cursor for the previous page of results

Hex List Projects

List all projects in your Hex workspace with optional filtering by status.

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	Hex API token (Personal or Workspace)
`limit`	number	No	Maximum number of projects to return (1-100)
`includeArchived`	boolean	No	Include archived projects in results
`statusFilter`	string	No	Filter by status: PUBLISHED, DRAFT, or ALL
`includeComponents`	boolean	No	Include components in results
`includeTrashed`	boolean	No	Include trashed projects in results
`creatorEmail`	string	No	Filter by creator email
`ownerEmail`	string	No	Filter by owner email
`collectionId`	string	No	Filter by collection UUID
`categories`	json	No	JSON array of category names to filter by (e.g., ["Marketing", "Finance"])
`sortBy`	string	No	Sort by field: CREATED_AT, LAST_EDITED_AT, or LAST_PUBLISHED_AT
`sortDirection`	string	No	Sort direction: ASC or DESC
`after`	string	No	Cursor to fetch the page of results after this value
`before`	string	No	Cursor to fetch the page of results before this value

Output

Parameter	Type	Description
`projects`	array	List of Hex projects
↳ `id`	string	Project UUID
↳ `title`	string	Project title
↳ `description`	string	Project description
↳ `status`	object	Project status
↳ `name`	string	Status name (e.g., PUBLISHED, DRAFT)
↳ `type`	string	Project type (PROJECT or COMPONENT)
↳ `creator`	object	Project creator
↳ `email`	string	Creator email
↳ `owner`	object	Project owner
↳ `email`	string	Owner email
↳ `lastEditedAt`	string	Last edited timestamp
↳ `lastPublishedAt`	string	Last published timestamp
↳ `createdAt`	string	Creation timestamp
↳ `archivedAt`	string	Archived timestamp
`total`	number	Total number of projects returned
`after`	string	Cursor for the next page of results
`before`	string	Cursor for the previous page of results

Hex List Users

List all users in the Hex workspace with optional filtering and sorting.

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	Hex API token (Personal or Workspace)
`limit`	number	No	Maximum number of users to return (1-100, default: 25)
`sortBy`	string	No	Sort by field: NAME or EMAIL
`sortDirection`	string	No	Sort direction: ASC or DESC
`groupId`	string	No	Filter users by group UUID
`userIds`	string	No	Comma-separated list of user UUIDs to filter by
`after`	string	No	Cursor to fetch the page of results after this value
`before`	string	No	Cursor to fetch the page of results before this value

Output

Parameter	Type	Description
`users`	array	List of workspace users
↳ `id`	string	User UUID
↳ `name`	string	User name
↳ `email`	string	User email
↳ `role`	string	User role (ADMIN, MANAGER, EDITOR, EXPLORER, MEMBER, GUEST, EMBEDDED_USER, ANONYMOUS)
↳ `lastLoginDate`	string	Last login timestamp
`total`	number	Total number of users returned
`after`	string	Cursor for the next page of results
`before`	string	Cursor for the previous page of results

Hex Run Project

Execute a published Hex project. Optionally pass input parameters and control caching behavior.

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	Hex API token (Personal or Workspace)
`projectId`	string	Yes	The UUID of the Hex project to run
`inputParams`	json	No	JSON object of input parameters for the project (e.g., {"date": "2024-01-01"})
`dryRun`	boolean	No	If true, perform a dry run without executing the project
`updateCache`	boolean	No	(Deprecated) If true, update the cached results after execution
`updatePublishedResults`	boolean	No	If true, update the published app results after execution
`useCachedSqlResults`	boolean	No	If true, use cached SQL results instead of re-running queries
`viewId`	string	No	Optional SavedView ID to use for the project run
`notifications`	json	No	JSON array of notification details to deliver once the run completes (e.g., [{"type": "FAILURE", "slackChannelIds": ["C0123456789"], "userIds": [], "groupIds": [], "includeSuccessScreenshot": false}]). type is ALL, SUCCESS, or FAILURE.

Output

Parameter	Type	Description
`projectId`	string	Project UUID
`runId`	string	Run UUID
`runUrl`	string	URL to view the run
`runStatusUrl`	string	URL to check run status
`traceId`	string	Trace ID for debugging
`projectVersion`	number	Project version number

Hex Update Collection

Update the name or description of an existing Hex collection.

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	Hex API token (Personal or Workspace)
`collectionId`	string	Yes	The UUID of the collection to update
`name`	string	No	New name for the collection
`description`	string	No	New description for the collection

Output

Parameter	Type	Description
`id`	string	Collection UUID
`name`	string	Collection name
`description`	string	Collection description
`creator`	object	Collection creator
↳ `email`	string	Creator email
↳ `id`	string	Creator UUID

Hex Update Group

Rename a Hex group or add/remove members from it.

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	Hex API token (Personal or Workspace)
`groupId`	string	Yes	The UUID of the group to update
`name`	string	No	New name for the group
`addUserIds`	json	No	JSON array of user UUIDs to add to the group (e.g., ["uuid1", "uuid2"])
`removeUserIds`	json	No	JSON array of user UUIDs to remove from the group (e.g., ["uuid1", "uuid2"])

Output

Parameter	Type	Description
`id`	string	Group UUID
`name`	string	Group name
`createdAt`	string	Creation timestamp

Hex Update Project

Update a Hex project status label (e.g., endorsement or custom workspace statuses).

Inputs and outputs

Input

Parameter	Type	Required	Description
`apiKey`	string	Yes	Hex API token (Personal or Workspace)
`projectId`	string	Yes	The UUID of the Hex project to update
`status`	string	Yes	New project status name (custom workspace status label)

Output

Parameter	Type	Description
`id`	string	Project UUID
`title`	string	Project title
`description`	string	Project description
`status`	object	Updated project status
↳ `name`	string	Status name (e.g., PUBLISHED, DRAFT)
`type`	string	Project type (PROJECT or COMPONENT)
`creator`	object	Project creator
↳ `email`	string	Creator email
`owner`	object	Project owner
↳ `email`	string	Owner email
`categories`	array	Project categories
↳ `name`	string	Category name
↳ `description`	string	Category description
`lastEditedAt`	string	Last edited timestamp
`lastPublishedAt`	string	Last published timestamp
`createdAt`	string	Creation timestamp
`archivedAt`	string	Archived timestamp
`trashedAt`	string	Trashed timestamp