## ListEnvironmentUsageRecords

**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

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

### Query Parameters

- `token: optional string`

- `pageSize: optional number`

### Body Parameters

- `filter: optional object { dateRange, projectId }`

  Filter options.

  - `dateRange: object { endTime, startTime }`

    Date range to query runtime records within.

    - `endTime: string`

      End time of the date range (exclusive).

    - `startTime: string`

      Start time of the date range (inclusive).

  - `projectId: optional string`

    Optional project ID to filter runtime records by.

- `pagination: optional object { token, pageSize }`

  Pagination options.

  - `token: optional string`

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

  - `pageSize: optional number`

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

### Returns

- `pagination: optional object { nextToken }`

  Pagination response.

  - `nextToken: optional string`

    Token passed for retrieving the next set of results. Empty if there are no
    more results

- `records: optional array of EnvironmentUsageRecord`

  List of environment runtime records.

  - `id: optional string`

    Environment usage record ID.

  - `createdAt: optional string`

    Time when the environment was created.

  - `environmentClassId: optional string`

    Environment class ID associated with the record.

  - `environmentId: optional string`

    Environment ID associated with the record.

  - `projectId: optional string`

    Project ID associated with the environment (if available).

  - `runnerId: optional string`

    Runner ID associated with the environment.

  - `stoppedAt: optional string`

    Time when the environment was stopped.

  - `userId: optional string`

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

### Example

```http
curl https://app.gitpod.io/api/gitpod.v1.UsageService/ListEnvironmentUsageRecords \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{}'
```

#### Response

```json
{
  "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"
    }
  ]
}
```