Get Execution Status

Check the status of an execution request

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

Returns the status of a query execution along with relevant metadata of the results if the execution is completed.

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.
• 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 result.

cURL

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

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"

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"