# Usage

## ListEnvironmentUsageRecords

`client.Usage.ListEnvironmentRuntimeRecords(ctx, params) (*RecordsPage[EnvironmentUsageRecord], error)`

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

### Parameters

- `params UsageListEnvironmentRuntimeRecordsParams`

  - `Token param.Field[string]`

    Query param

  - `PageSize param.Field[int64]`

    Query param

  - `Filter param.Field[UsageListEnvironmentRuntimeRecordsParamsFilter]`

    Body param: Filter options.

    - `DateRange UsageListEnvironmentRuntimeRecordsParamsFilterDateRange`

      Date range to query runtime records within.

      - `EndTime Time`

        End time of the date range (exclusive).

      - `StartTime Time`

        Start time of the date range (inclusive).

    - `ProjectID string`

      Optional project ID to filter runtime records by.

  - `Pagination param.Field[UsageListEnvironmentRuntimeRecordsParamsPagination]`

    Body param: Pagination options.

    - `Token string`

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

    - `PageSize int64`

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

### Returns

- `type EnvironmentUsageRecord struct{…}`

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

  - `ID string`

    Environment usage record ID.

  - `CreatedAt Time`

    Time when the environment was created.

  - `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 Time`

    Time when the environment was stopped.

  - `UserID string`

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

### Example

```go
package main

import (
  "context"
  "fmt"
  "time"

  "github.com/gitpod-io/gitpod-sdk-go"
  "github.com/gitpod-io/gitpod-sdk-go/option"
)

func main() {
  client := gitpod.NewClient(
    option.WithBearerToken("My Bearer Token"),
  )
  page, err := client.Usage.ListEnvironmentRuntimeRecords(context.TODO(), gitpod.UsageListEnvironmentRuntimeRecordsParams{
    Filter: gitpod.F(gitpod.UsageListEnvironmentRuntimeRecordsParamsFilter{
      DateRange: gitpod.F(gitpod.UsageListEnvironmentRuntimeRecordsParamsFilterDateRange{
        EndTime: gitpod.F(time.Now()),
        StartTime: gitpod.F(time.Now()),
      }),
      ProjectID: gitpod.F("d2c94c27-3b76-4a42-b88c-95a85e392c68"),
    }),
    Pagination: gitpod.F(gitpod.UsageListEnvironmentRuntimeRecordsParamsPagination{
      PageSize: gitpod.F(int64(100)),
    }),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", page)
}
```

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

## Domain Types

### Environment Usage Record

- `type EnvironmentUsageRecord struct{…}`

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

  - `ID string`

    Environment usage record ID.

  - `CreatedAt Time`

    Time when the environment was created.

  - `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 Time`

    Time when the environment was stopped.

  - `UserID string`

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