Get Execution Status

Check the status of an execution request

GET /v1/execution/{execution_id}/status

Try it

cURL

curl -X GET "https://api.dune.com/api/v1/execution/{{execution_id}}/status" -H x-dune-api-key:{{api_key}}

Success Response

{
  "execution_id": "01HKZJ2683PHF9Q9PHHQ8FW4Q1",
  "query_id": 3493826,
  "is_execution_finished": true,
  "state": "QUERY_STATE_COMPLETED",
  "submitted_at": "2025-10-22T10:31:04.222464Z",
  "expires_at": "2026-01-20T10:31:04.36241Z",
  "execution_started_at": "2025-10-22T10:31:05.123456Z",
  "execution_ended_at": "2025-10-22T10:31:15.789012Z",
  "execution_cost_credits": 10
}

You must pass the execution_id obtained from making an execute query or execute SQL POST request.

Returns the status of a query execution along with relevant metadata of the results if the execution is completed. This endpoint now includes detailed error information when a query fails, eliminating the need to call the results endpoint just to get error details.

Pricing

This endpoint has no charge and does not consume credits.

Execution States

Once an execution is triggered, it can be in one of the following states:

• QUERY_STATE_PENDING: The query execution is waiting for an execution slot.
• QUERY_STATE_EXECUTING: The query is currently executing.
• QUERY_STATE_FAILED: The query execution failed. This is a terminal state. The response will include detailed error information.
• QUERY_STATE_COMPLETED: The query execution completed successfully. You can retrieve the query result for this execution_id.
• QUERY_STATE_CANCELED: The query execution was canceled by the user.
• QUERY_STATE_EXPIRED: The query execution expired, and the result is no longer available.
• QUERY_STATE_COMPLETED_PARTIAL: The query execution was successful, but the result was truncated because it was too large. To receive the truncated result, set the allow_partial_results flag to true in the API request to fetch the result.

Error Response Fields

When a query execution fails (QUERY_STATE_FAILED), the response includes an error object with the following fields:

• type (string): Error type classification (e.g., FAILED_TYPE_EXECUTION_FAILED)
• message (string): Detailed error message explaining what went wrong, including line and column information
• metadata (object): Additional error context
  • line (integer): Line number where the error occurred
  • column (integer): Column position where the error occurred

cURL

curl -X GET "https://api.dune.com/api/v1/execution/{{execution_id}}/status" -H x-dune-api-key:{{api_key}}

Success Response

{
  "execution_id": "01HKZJ2683PHF9Q9PHHQ8FW4Q1",
  "query_id": 3493826,
  "is_execution_finished": true,
  "state": "QUERY_STATE_COMPLETED",
  "submitted_at": "2025-10-22T10:31:04.222464Z",
  "expires_at": "2026-01-20T10:31:04.36241Z",
  "execution_started_at": "2025-10-22T10:31:05.123456Z",
  "execution_ended_at": "2025-10-22T10:31:15.789012Z",
  "execution_cost_credits": 10
}

Headers

X-Dune-Api-Key · string · required

API Key for the service

Path Parameters

execution_id · string · required

Execution ID

Query Parameters

api_key · string

Alternative to using the X-Dune-Api-Key header

Response

200

application/json

OK

cancelled_at · string

Timestamp of when the query execution was cancelled, if applicable.

Example:

"2024-12-20T11:04:18.724658237Z"

error · object

In case the execution had an error, this object will contain the error details

Show child attributes

error. message · string

A descriptive message about the error.

Example:

"Error: Line 1:1: mismatched input 'selecdt'"

error. metadata · object

Metadata about the syntax error that occurred, if applicable.

Show child attributes

error.metadata. column · integer

The column number at which the syntax error occurred.

Example:

73

error.metadata. line · integer

The line number at which the syntax error occurred in the query.

Example:

10

error. type · string

The type of error that occurred.

Example:

"syntax_error"

execution_cost_credits · number

Cost of the execution

execution_ended_at · string

Timestamp of when the query execution ended.

Example:

"2024-12-20T11:04:18.724658237Z"

execution_id · string

Unique identifier for the execution of the query and corresponding result.

Example:

"01HKZJ2683PHF9Q9PHHQ8FW4Q1"

execution_started_at · string

Timestamp of when the query execution started.

Example:

"2024-12-20T11:04:18.724658237Z"

expires_at · string

Timestamp of when the query result expires.

Example:

"2024-12-20T11:04:18.724658237Z"

is_execution_finished · boolean

Whether the state of the query execution is terminal. This can be used for polling purposes.

Example:

true

max_inflight_interactive_executions · integer

Number of interactive executions this customer can have running in parallel

Example:

3

max_inflight_interactive_reached · integer

Total number of interactive executions this user has submitted which are still in progress only set to > 0 if the user has reached the limit of concurrent interactive executions

Example:

5

query_id · integer

Unique identifier of the query.

Example:

1234

queue_position · integer

Example:

1

result_metadata · object

Metadata about the execution of the query, including details like column names, row counts, and execution times.

Show child attributes

result_metadata. column_names · string[]

Names of the columns in the result set.

Example:

["Rank", "Project", "Volume"]

result_metadata. column_types · string[]

Types of the columns in the result set.

Example:

["double", "varchar", "bigint"]

result_metadata. datapoint_count · integer

Results cell count is used for billing/pricing plans here we expose the these values to the user, so that they can track their costs

Example:

1000

result_metadata. execution_time_millis · integer

Time in milliseconds that the query took to execute.

Example:

1000

result_metadata. pending_time_millis · integer

Time in milliseconds that the query was pending before execution.

Example:

1000

result_metadata. result_set_bytes · integer

ResultSetBytes represents the raw data bytes returned by the SQL execution engine, it includes:

• total nr of bytes used on 1 line with all the column names (the header of the result set)
• total nr of bytes for all the row values (the result set of rows)

it doesn't include overheads such as the presence of column names for every row in the JSON result type. it also doesn't include opmitizations such as compression

Example:

1000

result_metadata. row_count · integer

Number of rows in the result set for the current page of results.

Example:

10

result_metadata. total_result_set_bytes · integer

Total number of bytes in the result set. This doesn't include the json representation overhead.

Example:

10000

result_metadata. total_row_count · integer

Number of rows in the result set for the entire result set.

Example:

1000

state · string

The state of the query execution.

Example:

"QUERY_STATE_COMPLETED"

submitted_at · string

Timestamp of when the query was submitted.

Example:

"2024-12-20T11:04:18.724658237Z"