ListEnvironmentUsageRecords

client.usage.listEnvironmentRuntimeRecords(, ?): RecordsPage<EnvironmentUsageRecord { id, createdAt, environmentClassId, 5 more } >

POST/gitpod.v1.UsageService/ListEnvironmentUsageRecords

Lists completed environment runtime records within a specified date range.

Returns a list of environment runtime records that were completed within the specified date range. Records of currently running environments are not included.

Use this method to:

View environment runtime records
Filter by project
Create custom usage reports

Example

filter:
  projectId: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  dateRange:
    startTime: "2024-01-01T00:00:00Z"
    endTime: "2024-01-02T00:00:00Z"
pagination:
  pageSize: 100

ParametersExpand Collapse

params: UsageListEnvironmentRuntimeRecordsParams { token, pageSize, filter, pagination }

token?: string

Query param

pageSize?: number

Query param

maximum100

minimum0

filter?: Filter

Body param: Filter options.

dateRange: DateRange { endTime, startTime }

Date range to query runtime records within.

endTime: string

End time of the date range (exclusive).

formatdate-time

startTime: string

Start time of the date range (inclusive).

formatdate-time

projectId?: string

Optional project ID to filter runtime records by.

pagination?: Pagination

Body param: Pagination options.

token?: string

Token for the next set of results that was returned as next_token of a PaginationResponse

pageSize?: number

Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100.

formatint32

maximum100

ReturnsExpand Collapse

EnvironmentUsageRecord { id, createdAt, environmentClassId, 5 more }

EnvironmentUsageRecord represents a record of an environment from start to stop.

id?: string

Environment usage record ID.

createdAt?: string

Time when the environment was created.

formatdate-time

environmentClassId?: string

Environment class ID associated with the record.

environmentId?: string

Environment ID associated with the record.

projectId?: string

Project ID associated with the environment (if available).

runnerId?: string

Runner ID associated with the environment.

stoppedAt?: string

Time when the environment was stopped.

formatdate-time

userId?: string

User ID is the ID of the user who created the environment associated with the record.

ListEnvironmentUsageRecords

import Gitpod from '@gitpod/sdk';

const client = new Gitpod({
  bearerToken: process.env['GITPOD_API_KEY'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const environmentUsageRecord of client.usage.listEnvironmentRuntimeRecords({
  filter: {
    dateRange: { endTime: '2024-01-02T00:00:00Z', startTime: '2024-01-01T00:00:00Z' },
    projectId: 'd2c94c27-3b76-4a42-b88c-95a85e392c68',
  },
  pagination: { pageSize: 100 },
})) {
  console.log(environmentUsageRecord.id);
}

{
  "pagination": {
    "nextToken": "nextToken"
  },
  "records": [
    {
      "id": "id",
      "createdAt": "2019-12-27T18:11:19.117Z",
      "environmentClassId": "environmentClassId",
      "environmentId": "environmentId",
      "projectId": "projectId",
      "runnerId": "runnerId",
      "stoppedAt": "2019-12-27T18:11:19.117Z",
      "userId": "userId"
    }
  ]
}

Returns Examples

{
  "pagination": {
    "nextToken": "nextToken"
  },
  "records": [
    {
      "id": "id",
      "createdAt": "2019-12-27T18:11:19.117Z",
      "environmentClassId": "environmentClassId",
      "environmentId": "environmentId",
      "projectId": "projectId",
      "runnerId": "runnerId",
      "stoppedAt": "2019-12-27T18:11:19.117Z",
      "userId": "userId"
    }
  ]
}