Skip to main content

Usage

With this API, you can retrieve the count of Dremio Consumption Units (DCU) used by jobs run within projects or on engines within projects. The DCUs are added together by hour or by day. You can retrieve the usage for various time periods up to 1 year in the past.

note

There is a lag of 1 to 2 hours between the time that a job ends and the time that the number of DCUs used by the job is available to be added into results returned by this API.

Usage Object 
{
  "data": [
    {
      "id": "95c31978-63c6-437c-9501-951cd712fdc6",
      "type": "PROJECT",
      "startTime": "2024-07-25T00:00:00+0000",
      "endTime": "2024-07-26T00:00:00+0000",
      "usage": 7.2
    },
    {
      "id": "95c31978-63c6-437c-9501-951cd712fdc6",
      "type": "PROJECT",
      "startTime": "2024-07-24T00:00:00+0000",
      "endTime": "2024-07-25T00:00:00+0000",
      "usage": 96.2
    },
    {
      "id": "95c31978-63c6-437c-9501-951cd712fdc6",
      "type": "PROJECT",
      "startTime": "2024-07-23T00:00:00+0000",
      "endTime": "2024-07-24T00:00:00+0000",
      "usage": 3.989
    }
  ],
  "previousPageToken": null,
  "nextPageToken": null
}

Usage Attributes​

data Array of Object

List of usage objects for the project or engine.

previousPageToken String

Token for retrieving the previous page of usage objects. If the project or engine has more usage objects than the maximum per page (default 20), the response will include a previousPageToken after the data array. If you use the nextPageToken value in a request URL as the pageToken value to retrieve the next page of 20 results, you can use the previousPageToken in a subsequent request URL to navigate to the previous page of results. Do not change any other query parameters included in the request URL when you use pageToken. Read pageToken Query Parameter for usage examples.

Example: ARbnWkcPVVJMWSIGRU2HSU3EVAA=

nextPageToken String

Token for retrieving the next page of usage objects. If the project or engine has more usage objects than the maximum per page (default 20), the response will include a nextPageToken after the data array. Use the nextPageToken value in your request URL as the pageToken value. Do not change any other query parameters included in the request URL when you use pageToken. Read pageToken Query Parameter for usage examples.

Example: DNJePkhPVVJMWSIGRU3HSU7FKAI=

Attributes of the data Array​

id String (UUID)

The ID for the project or engine of which the object records the usage.

Example: 95c31978-63c6-437c-9501-951cd712fdc6

type String

Specifies whether the usage is reported for a project or for an engine.

Enum: PROJECT, ENGINE

Example: PROJECT

startTime String

The starting date and time of the period for which the usage is reported in the object.

Example: 2024-07-25T00:00:00+0000

endTime String

The ending date and time of the period for which the usage is reported in the object.

Example: 2024-07-26T00:00:00+0000

usage Float

The usage for the object in Dremio Consumption Units (DCUs).

Example: 7.2

Retrieving Usage Objects​

Retrieves a paginated array of usage objects for all projects or engines in the organization that the requestor belongs to. The default is all projects, with 20 usage objects per page.

Method and URL 
GET /v0/usage

Parameters​

pageToken Query   String   Optional

Used to get the next/previous page of paginated usages. Other parameters must not change when using the pageToken.

Token for retrieving the next or previous page of usage objects. If the Dremio instance has more usage objects than the maximum per page (default 20), the response will include a nextPageToken after the data array. Use the nextPageToken value in your request URL as the pageToken value. The response for the next page of results will include a previousPageToken after the data array, which you can use in a request URL as the pageToken value to return to the previous page of results. Do not change any other query parameters included in the request URL when you use pageToken. Read pageToken Query Parameter for usage examples.

Example: &pageToken=DNJePkhPVVJMWSIGRU3HSU7FKAI=

maxResults Query   Integer   Optional

The maximum number of usage objects to return in the response. The server may return fewer results, but not more. The default is 20. Read maxResults Query Parameter for usage examples.

Example: ?maxResults=25

filter Query   String   Optional

Allows filtering on id and start_time in milliseconds since UNIX epoch. The maximum supported date period is 90 days, and data cannot be retrieved beyond than 1 year in the past. The default is 30 days from the time of request.

Example: ?filter == '95c31978-63c6-437c-9501-951cd712fdc6' && start_time >= 1638234061000

frequency Query   String   Optional

Whether to group the usage data in the response by day or hour. Default is DAILY.

Enum: DAILY, HOURLY

Example: ?frequency=HOURLY

groupBy Query   String   Optional

Whether to group the usage data in the response by project or engine. Default is PROJECT.

Enum: PROJECT, ENGINE

Example: ?groupBy=ENGINE

Example Request Using filter Query Parameter 
curl -X GET "http://api.dremio.cloud/v0/usage?filter=id=='671653b1-5a63-44db-a88e-1aa89cecf0d0'" \
-H "Authorization: Bearer <Authorization token>" \
-H "Content-Type: application/json"

The example request above retrieves usage objects for the project whose ID is specified in the request URL with the filter query parameter for the previous 30 days.

Example Request Using pageToken, maxResults, frequency, and groupBy Query Parameters 
curl -X GET "http://example.com/v0/usage?pageToken=CHH86FGBV450ICTDS42YY6DLI09I=&maxResults=10&frequency=HOURLY&groupBy=ENGINE" \
-H "Authorization: Bearer <personal access token>" \
-H "Content-Type: application/json"

The example request above uses the token from either the previousPageToken or nextPageToken of a response to retrieve the previous or next page of usage objects. The example also specifies to retrieve no more than 10 usage objects that should each represent 1 hour of usage. No filter is specified, so the request retrieves the amount of usage for each project and engine in the organization for the previous 30 days.

note

Except for the value of the pageToken parameter, the values of all of the other parameters are the same as in previous requests for subsets of the same set of usage objects. Changing the value of maxResults would change the number of usage objects returned per page, therefore changing the pagination. Changing the value of frequency, groupBy, or both would retrieve an entirely different set of usage objects, as would using a non-default values for filter.

Response Status Codes​

200   OK

400   Bad Request

401   Unauthorized

404   Not Found