Engines

An engine represents a Dremio entity that manages compute resources. Each engine has one or more replicas that are created for executing queries. An engine replica is a logical group of executors defined by the engine size. This API allows you to list existing engines and add, modify, enable/disable, and delete engines.

Engines Object

{
  "id": "e1cb20ff-a234-46f1-9f97-550e2bb5310f",
  "name": "firstEngine",
  "size": "XX_SMALL_V1",
  "activeReplicas": 0,
  "minReplicas": 0,
  "maxReplicas": 10,
  "autoStopDelaySeconds": 300,
  "queueTimeLimitSeconds": 300,
  "runtimeLimitSeconds": 0,
  "drainTimeLimitSeconds": 0,
  "state": "ENABLED",
  "queriedAt": "Thu Jan 01 00:00:00 UTC 2021",
  "statusChangedAt": "Thu Aug 19 14:39:40 UTC 2021",
  "description": "",
  "maxConcurrency": 4,
  "additionalEngineStateInfo": "NONE"
}

Engine Attributes

id String (UUID)

UUID of an engine.

name String

The user-defined name for an engine.

Example: firstEngine

size String

The size of the engine. Each engine replica that is created will be of this size.

Valid Values: XX_SMALL_V1, X_SMALL_V1, SMALL_V1, MEDIUM_V1, LARGE_V1, X_LARGE_V1, XX_LARGE_V1, XXX_LARGE_V1

Example: SMALL_V1

activeReplicas Integer

The number of engine replicas that are currently active.

minReplicas Integer

The minimum number of engine replicas that will be enabled at any given time.

maxReplicas Integer

The maximum number of engine replicas that will be enabled at any given time.

autoStopDelaySeconds Integer

The time (in seconds) that auto-stop is delayed.

Example: 300

queueTimeLimitSeconds Integer

The maximum amount of time (in seconds) that a query will wait in the engine's queue before it is canceled. The typical time to start a new replica is two minutes (120 seconds), so we recommend setting this to more than 120 seconds. Changing this setting does not affect queries that are currently running or already in the queue.

Example: 300

runtimeLimitSeconds Integer

The maximum amount of time (in seconds) that a query can run before being terminated.

drainTimeLimitSeconds Integer

The maximum amount of time (in seconds) that an engine replica will continue to run after the engine is resized, disabled, or deleted before it is terminated and the running queries are terminated.

Example: 0

state String

The current state of the engine.

Valid Values: DELETING, DISABLED, DISABLING, ENABLED, ENABLING, INVALID

Example: ENABLED

queriedAt String

The date and time that the engine was last used to execute a query.

Example: Wed Oct 08 15:29:11 UTC 2025

statusChangedAt String

The date and time (in UTC) that the state of the engine changed.

Example: Tue Oct 14 03:54:07 UTC 2025

description String

The description for the engine.

Example: engine for sales workloads

maxConcurrency Integer

The maximum number of concurrent queries that an engine replica can run.

additionalEngineStateInfo String

Not used. Has the value NONE.

List All Engines

Method and URL

GET /v0/projects/{project_id}/engines

Parameters

project_id Path String (UUID)

Example

Request

curl -X GET "https://api.dremio.cloud/v0/projects/$PROJECT_ID/engines" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json'

Response

[
  {
    "id": "e1cb20ff-a234-46f1-9f97-550e2bb5310f",
    "name": "firstEngine",
    "size": "XX_SMALL_V1",
    "activeReplicas": 0,
    "minReplicas": 0,
    "maxReplicas": 10,
    "autoStopDelaySeconds": 300,
    "queueTimeLimitSeconds": 300,
    "runtimeLimitSeconds": 0,
    "drainTimeLimitSeconds": 0,
    "state": "ENABLED",
    "queriedAt": "Thu Jan 01 00:00:00 UTC 2021",
    "statusChangedAt": "Thu Aug 19 14:39:40 UTC 2021",
    "description": "",
    "maxConcurrency": 4,
    "additionalEngineStateInfo": "NONE"
  },
  {
    "id": "a99eb46a-8121-4b79-b2ed-917e07f96092",
    "name": "preview",
    "size": "XX_SMALL_V1",
    "activeReplicas": 0,
    "minReplicas": 0,
    "maxReplicas": 1,
    "autoStopDelaySeconds": 180,
    "queueTimeLimitSeconds": 300,
    "runtimeLimitSeconds": 0,
    "drainTimeLimitSeconds": 0,
    "state": "ENABLED",
    "queriedAt": "Thu Jan 01 00:00:00 UTC 2021",
    "statusChangedAt": "Fri Aug 20 03:58:54 UTC 2021",
    "description": "",
    "maxConcurrency": 4,
    "additionalEngineStateInfo": "NONE"
  }
]

Response Status Codes

200   OK

400   Bad Request

401   Unauthorized

Add an Engine

Method and URL

POST /v0/projects/{project_id}/engines

Parameters

project_id Path String (UUID)

name Body String

The user-defined name for an engine.

Example: newengine

size Body String

The size of the engine that you want to create. Each engine replica that is created will be of this size.

Valid Values: XX_SMALL_V1, X_SMALL_V1, SMALL_V1, MEDIUM_V1, LARGE_V1, X_LARGE_V1, XX_LARGE_V1, XXX_LARGE_V1

Example: XX_SMALL_V1

minReplicas Body Integer

The minimum number of engine replicas that will be enabled at any given time.

maxReplicas Body Integer

The maximum number of engine replicas that will be enabled at any given time.

autoStopDelaySeconds Body Integer

The time (in seconds) that auto-stop is delayed.

Example: 7200

queueTimeLimitSeconds Body Integer

The maximum amount of time (in seconds) that a query will wait in the engine's queue before it is canceled. This should not be set to less than two minutes (120 seconds), which is the typical time it takes to start a new replica. Changing this setting does not affect queries that are currently running or in the queue.

Example: 300

runtimeLimitSeconds Body Integer

The maximum amount of time (in seconds) that a query can run before being terminated.

drainTimeLimitSeconds Body Integer

The maximum amount of time (in seconds) that an engine replica will continue to run after the engine is resized, disabled, or deleted before it is terminated and the running queries are terminated.

Example: 1800

description Body String Optional

The description for the engine.

Example: engine description

maxConcurrency Body Integer

The maximum number of concurrent queries that an engine replica can handle.

requestId Body String (UUID)

The user-defined idempotency key, which is a unique value generated by the user that the server uses to recognize subsequent retries of the same request. Generate the request ID by using a UUID generator tool. See idempotent requests for more information.

Example

Request

curl -X POST "https://api.dremio.cloud/v0/projects/$PROJECT_ID/engines" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
  "name": "newengine",
  "size": "XX_SMALL_V1",
  "minReplicas": 0,
  "maxReplicas": 1,
  "autoStopDelaySeconds": 7200,
  "queueTimeLimitSeconds": 300,
  "runtimeLimitSeconds": 0,
  "drainTimeLimitSeconds": 1800,
  "description": "engine description",
  "maxConcurrency": 2,
  "requestId": "d9904076-01db-11ec-9a03-0242ac130003"
}'

Response

{
  "id": "168acd56-16a0-47df-91f8-5487a8fccfc4"
}

Response Status Codes

200   OK

400   Bad Request

401   Unauthorized

405   Method Not Allowed

500   Internal Server Error

Retrieve an Engine

Method and URL

GET /v0/projects/{project_id}/engines/{id}

Parameters

project_id Path String (UUID)

id Path String (UUID)

UUID of the engine for which you want to retrieve metadata.

Example

Request

curl -X GET "https://api.dremio.cloud/v0/projects/$PROJECT_ID/engines/$ENGINE_ID" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json'

Response

{
  "id": "168acd56-16a0-47df-91f8-5487a8fccfc4",
  "name": "newengine",
  "size": "XX_SMALL_V1",
  "activeReplicas": 0,
  "minReplicas": 0,
  "maxReplicas": 1,
  "autoStopDelaySeconds": 7200,
  "queueTimeLimitSeconds": 300,
  "runtimeLimitSeconds": 0,
  "drainTimeLimitSeconds": 1800,
  "state": "ENABLED",
  "queriedAt": "Thu Jan 01 00:00:00 UTC 2021",
  "statusChangedAt": "Fri Aug 20 17:29:18 UTC 2021",
  "description": "engine description",
  "maxConcurrency": 2,
  "additionalEngineStateInfo": "NONE"
}

Response Status Codes

200   OK

400   Bad Request

401   Unauthorized

500   Internal Server Error

Modify an Engine

Method and URL

PUT /v0/projects/{project_id}/engines/{id}

Parameters

project_id Path String (UUID)

id Path String (UUID)

UUID of the engine that you want to modify.

size Body String Optional

The size of the engine that you want to change to. Each engine replica that is modified will be of this size.

Valid Values: XX_SMALL_V1, X_SMALL_V1, SMALL_V1, MEDIUM_V1, LARGE_V1, X_LARGE_V1, XX_LARGE_V1, XXX_LARGE_V1

Example: XX_SMALL_V1

minReplicas Body Integer Optional

The minimum number of engine replicas that will be enabled at any given time.

maxReplicas Body Integer Optional

The maximum number of engine replicas that will be enabled at any given time.

autoStopDelaySeconds Body Integer Optional

The time (in seconds) that auto-stop is delayed.

Example: 7200

queueTimeLimitSeconds Body Integer Optional

Example: 300

runtimeLimitSeconds Body Integer Optional

The maximum amount of time (in seconds) that a query can run before being terminated.

drainTimeLimitSeconds Body Integer Optional

The maximum amount of time (in seconds) that an engine replica will continue to run after the engine is resized, disabled, or deleted before it is terminated and the running queries are terminated.

Example: 1800

description Body String Optional

The description for the engine you are modifying.

Example: modified engine description

maxConcurrency Body Integer Optional

The maximum number of concurrent queries that an engine replica can run.

Example

Request

curl -X PUT "https://api.dremio.cloud/v0/projects/$PROJECT_ID/engines/$ENGINE_ID" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
      "description": "modified engine description",
      "size": "XX_SMALL_V1",
      "autoStopDelaySeconds": 7200,
      "drainTimeLimitSeconds": 1800,
      "maxConcurrency": 2,
      "maxReplicas": 1,
      "minReplicas": 0,
      "queueTimeLimitSeconds": 300,
      "runtimeLimitSeconds": 0
    }'

A successful request returns an empty response body with HTTP status 204 No Content.

Response Status Codes

204   No Content

400   Bad Request

401   Unauthorized

500   Internal Server Error

Enable an Engine

Method and URL

PUT /v0/projects/{project_id}/engines/{id}/enable

Parameters

project_id Path String (UUID)

id Path String (UUID)

UUID of the engine that you want to enable.

Example

Request

curl -X PUT "https://api.dremio.cloud/v0/projects/$PROJECT_ID/engines/$ENGINE_ID/enable" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json'

A successful request returns an empty response body with HTTP status 204 No Content.

Response Status Codes

204   No Content

401   Unauthorized

500   Internal Server Error

Disable an Engine

Method and URL

PUT /v0/projects/{project_id}/engines/{id}/disable

Parameters

project_id Path String (UUID)

id Path String (UUID)

UUID of the engine that you want to disable.

Example

Request

curl -X PUT "https://api.dremio.cloud/v0/projects/$PROJECT_ID/engines/$ENGINE_ID/disable" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json'

A successful request returns an empty response body with HTTP status 204 No Content.

Response Status Codes

204   No Content

401   Unauthorized

500   Internal Server Error

Delete an Engine

Method and URL

DELETE /v0/projects/{project_id}/engines/{id}

Parameters

project_id Path String (UUID)

id Path String (UUID)

UUID of the engine that you want to delete.

Example

Request

curl -X DELETE "https://api.dremio.cloud/v0/projects/$PROJECT_ID/engines/$ENGINE_ID" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json'

A successful request returns an empty response body with HTTP status 204 No Content.

Response Status Codes

204   No Content

401   Unauthorized

500   Internal Server Error

Engine Attributes​

List All Engines​

Parameters​

Example​

Response Status Codes​

Add an Engine​

Parameters​

Example​

Response Status Codes​

Retrieve an Engine​

Parameters​

Example​

Response Status Codes​

Modify an Engine​

Parameters​

Example​

Response Status Codes​

Enable an Engine​

Parameters​

Example​

Response Status Codes​

Disable an Engine​

Parameters​

Example​

Response Status Codes​

Delete an Engine​

Parameters​

Example​

Response Status Codes​

Engine Attributes

List All Engines

Parameters

Example

Response Status Codes

Add an Engine

Parameters

Example

Response Status Codes

Retrieve an Engine

Parameters

Example

Response Status Codes

Modify an Engine

Parameters

Example

Response Status Codes

Enable an Engine

Parameters

Example

Response Status Codes

Disable an Engine

Parameters

Example

Response Status Codes

Delete an Engine

Parameters

Example

Response Status Codes