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 one year in the past.
There is a lag of between one to two 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.
{
"id": "95c31978-63c6-437c-9501-951cd712fdc6",
"type": "PROJECT",
"startTime": "2021-07-21T17:00:00Z",
"endTime": "2021-07-21T18:00:00Z",
"usage": 7.2
}
Usage Attributes
id String (UUID)
An ID that identifies the project or engine that the object records the usage of.
Example: 95c31978-63c6-437c-9501-951cd712fdc6
type String
Explains whether the usage is reported for a project or for an engine.
Enum: PROJECT, ENGINE
Example: PROJECT
startTime String
The date and time of the start of the time period for which the usage is reported in the object.
Example: 2021-07-21T17:00:00Z
endTime String
The date and time of the end of the time period for which the usage is reported in the object.
Example: 2021-07-21T18:00:00Z
usage Float
A float number that gives the usage for the object with the ID reported in the id field. Usage is measured in Dremio Consumption Units (DCU).
Example: 7.2
Usages Object{
"data": [
{
Usage object
},
{
Usage object
},
...
],
"previousPageToken": "",
"nextPageToken": "CAIaBkhPVVJMWSIGRU5HSU5FKAI="
}
Usages Attributes
data Array of Object
An array of returned usage objects.
previousPageToken String
An token that can be used in requests to retrieve the previous page of usage objects in a usages object.
Example: ""
nextPageToken String
An token that can be used in requests to retrieve the next page of usage objects in a usages object.
Example: CAIaBkhPVVJMWSIGRU5HSU5FKAI=
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.
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.
Example: CAIaBkhPVVJMWSIGRU5HSU5FKAI=
maxResults Query Integer Optional
Maximum number of usage objects to return per page. The default is 20 usage objects.
Example: 25
filter Query String Optional
Allows filtering on id and start_time, which is in milliseconds since UNIX epoch. The maximum supported date period is 90 days, and data cannot be retrieved further than 1 year in the past. The default is 30 days from the time of request.
Example: id == '95c31978-63c6-437c-9501-951cd712fdc6' && start_time >= 1638234061000 && start_time < 1638320461000
frequency Query String Optional
Whether to group the usage data by day or hour. The default is DAILY.
Enum: DAILY, HOURLY
groupBy Query String Optional
Whether to group the results by project or engine. Default is by project. The default is PROJECT. This parameter is not required.
Enum: PROJECT, ENGINE
Examples of Requests
This example retrieves thirty usage
objects (one for each of the past thirty days) for the project that has the ID specified in the filter. For each day, the usages of the jobs that ran in the project that day are added together.
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"
This example uses the token from either the previousPageToken
or nextPageToken
of a usages
object to retrieve the previous or next page of usage objects. The example also specifies to retrieve only up to ten usage
objects. Each usage object represents an hour of usage. No filter is specified, so the request retrieves the amount of usage for each project and engine in the organization connected to, and for the default of the previous thirty days.
Except for the value of the pageToken
parameter, the values of all of the other parameters are the same as they were 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. So, too, would using a non-default values for filter
.
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"
Responses
200 OK400 Bad Request
401 Unauthorized
404 Not Found