# Method: mediaItems.list

- [HTTP request](https://developers.google.com/photos/ambient/reference/rest/v1/mediaItems/list#body.HTTP_TEMPLATE)
- [Query parameters](https://developers.google.com/photos/ambient/reference/rest/v1/mediaItems/list#body.QUERY_PARAMETERS)
- [Request body](https://developers.google.com/photos/ambient/reference/rest/v1/mediaItems/list#body.request_body)
- [Response body](https://developers.google.com/photos/ambient/reference/rest/v1/mediaItems/list#body.response_body)
  - [JSON representation](https://developers.google.com/photos/ambient/reference/rest/v1/mediaItems/list#body.ListMediaItemsResponse.SCHEMA_REPRESENTATION)
- [Authorization scopes](https://developers.google.com/photos/ambient/reference/rest/v1/mediaItems/list#body.aspect)
- [Try it!](https://developers.google.com/photos/ambient/reference/rest/v1/mediaItems/list#try-it)

Returns a list of ambient media items from user-configured media sources for the specified device.

By default, `listMediaItems` provides the Ambient experience, returning a curated set of media items from all user-configured sources.

Optionally, you can include `mediaSourceId` in the request to retrieve a paginated list of items from a specific media source, allowing for more traditional filtering.

Client applications are limited to 240 requests per device per day.

A `FAILED_PRECONDITION` error occurs if the user has not configured any media sources.

### HTTP request

`GET https://photosambient.googleapis.com/v1/mediaItems`

The URL uses [gRPC Transcoding](https://google.aip.dev/127) syntax.

### Query parameters

| Parameters ||
|---|---|
| `deviceId` | `string` Required. The unique identifier for this device. |
| `mediaSourceId` | `string` Optional. **For the Ambient experience** , omit this field. This will return a curated set of media items from all configured sources. The number of items returned will honor your `pageSize` request, up to a maximum of 100 items. If specified, only items from the specified media source will be returned. The `id` must be of a source selected by the user for the specified device (i.e. one of `AmbientDevice.media_sources.id`). Note, `highlights` is not supported even if it is a selected source for this device by the user. Setting this field to `highlights` will return a `INVALID_ARGUMENT` error. |
| `pageSize` | `integer` Optional. The maximum number of media items to return. The service will honor your `pageSize` request, though it may return fewer items than specified (including zero results). If `pageSize` is unspecified or set to 0, at most 50 media items will be returned. Values greater than 100 will be coerced down to the maximum allowed value of 100. Providing a negative value will result in an `INVALID_ARGUMENT` error. |
| `pageToken` | `string` Optional. A page token, received from a previous `mediaItems.list` call. Provide this to retrieve the subsequent page. |

### Request body

The request body must be empty.

### Response body

Response to the `mediaItems.list` method.

If successful, the response body contains data with the following structure:

| JSON representation |
|---|
| ``` { "mediaItems": [ { object (`https://developers.google.com/photos/ambient/reference/rest/v1/mediaItems#AmbientMediaItem`) } ], "nextPageToken": string } ``` |

| Fields ||
|---|---|
| `mediaItems[]` | ``object (`https://developers.google.com/photos/ambient/reference/rest/v1/mediaItems#AmbientMediaItem`)`` A page of ambient media items for the device to display. |
| `nextPageToken` | `string` If set, this field can be used as the `pageToken` in a subsequent `mediaItems.list` call to retrieve the next page of items. If this field is omitted, it is not necessarily an indication that no more content is available to be fetched, but rather that the subsequent page of content may contain media items that were already returned in prior pages. |

### Authorization scopes

Requires the following OAuth scope:

- `https://www.googleapis.com/auth/photosambient.mediaitems`