# Create and manage sessions

Sessions are at the heart of the Picker API, providing a secure and controlled
way for users to select photos and videos from their Google Photos library. This
guide outlines how to create, manage, and effectively poll sessions to enable
seamless photo selection in your app.

## Before you start

- **Configure your app:** Enable the API and set up authentication. See [Configure your app](https://developers.google.com/photos/overview/configure-your-app) for detailed steps.
- **Understand the flow:** Review [get started with the Picker API](https://developers.google.com/photos/picker/guides/get-started-picker) for an overview of the entire photo selection process.
- **Review required authorization scopes** : Working with sessions requires the `photospicker.mediaitems.readonly` scope. For more information on scopes, see [Authorization scopes](https://developers.google.com/photos/overview/authorization).

## Session lifecycle

The Picker API provides methods to create, retrieve information about, and
delete sessions. After authenticating your users, you can use sessions to manage
the photo picking lifecycle.

1. [Create a session](https://developers.google.com/photos/picker/guides/sessions#create-sessions) to enable a user to select media items.
2. [Poll the session](https://developers.google.com/photos/picker/guides/sessions#poll-monitor-sessions) to check when the user has finished selecting media items.
3. [List and retrieve the media items](https://developers.google.com/photos/picker/guides/media-items).
4. [Clean up the session](https://developers.google.com/photos/picker/guides/sessions#delete-and-clean) by deleting it.

### Create sessions

Create a session so your users can securely pick photos directly from their
Google Photos app, and share them back to your application.

`sessions.create` generates a new session, returning a unique `pickerUri` that
you can present to your users. The session remains active until either the user
has successfully selected media items, or the session times out. For web-based
applications, you can append `/autoclose` to the `pickerUri` to automatically
close the Google Photos window or tab after the user completes their
selection---see [Photo picking: what users
see](https://developers.google.com/photos/picker/guides/picking-experience) for details.

> [!NOTE]
> **Note:** The `pickerUri` cannot be opened in an iframe due to security reasons.

#### Session limits

Be aware of session limits. The Picker API enforces limits on the number of
sessions you can create to ensure responsible usage and prevent abuse. Under
normal circumstances, you're unlikely to reach these limits. However, you should
track and [clean up sessions proactively](https://developers.google.com/photos/picker/guides/sessions#delete-and-clean) to avoid any
issues.

> [!NOTE]
> **Note:** During development, if you create test sessions without storing their IDs, you won't be able to retrieve or delete them individually. Be mindful of this to avoid creating untracked sessions.

### Poll and monitor sessions

Once a session is created, periodically poll the `sessions.get` endpoint to get
the status of a session. The `mediaItemsSet` property in the response returns
`true` when the user has completed their selection.

Make sure to use efficient polling. The `sessions.get` response includes the
`pollingConfig` object. Use the following fields to help you avoid unnecessary
calls and create a smooth user experience:

- **`pollInterval`**: optimal polling intervals
- **`timeoutIn`**: timeout duration

See the [Example polling flow](https://developers.google.com/photos/picker/guides/sessions#example-polling-flow) for more details.

### Delete and clean up sessions

`sessions.delete` removes a session, typically used for cleanup after the user
has finished selecting media or if the session times out.

It's a best practice to delete sessions once the user has selected media items
and [your app has retrieved the media item
bytes](https://developers.google.com/photos/picker/guides/media-items).

## Example polling flow

This is an example of creating and polling a session. After first authenticating
your user, create a new session.

1. **Create a session:** Call `sessions.create` to initiate a new session and obtain the `pickerUri`.
2. **Present the `pickerUri` to the user:** Display the URL or generate a QR code for the user to scan. Read an overview of the [user's picking experience](https://developers.google.com/photos/picker/guides/picking-experience).
3. **Poll the session:**
   1. Use the recommended pollInterval from `pollingConfig`.
   2. Check if `mediaItemsSet` is true.
      1. If `true`, proceed to list the selected media items.
      2. If `false`, continue polling until `timeoutIn` is reached.
   3. Handle timeouts and cancellations gracefully.

    GET https://photoslibrary.googleapis.com/v1/sessions/{sessionId}

Here's an example response:

    {
      "id": string,
      "pickerUri": string,
      "pollingConfig": {
        object (PollingConfig)
      },
      "mediaItemsSet": boolean
    }

Present the `pickerUri` to the user, and then begin to poll the session.

Check the response for the following:

- `mediaItemsSet`: true if the user has finished selecting media items
- `pollingConfig.pollInterval`: recommended time to wait before the next poll
- `pollingConfig.timeoutIn`: total time to wait before timing out

If `mediaItemsSet` is false and `timeoutIn` has not been reached, wait for
`pollInterval` and then poll again.

If `mediaItemsSet` is true, proceed to list the selected media items.

If `timeoutIn` is reached, handle the timeout gracefully.