# Using Notetaker retention policies

Source: https://developer.nylas.com/docs/v3/notetaker/retention-policies/

Every recorded meeting can produce up to five files: a recording, transcript, thumbnail, and (when enabled) a summary and action items. By default, Nylas keeps them for **14 days**, then deletes them. Change the duration by setting `retention_time` (in seconds) anywhere `notetaker_settings` is accepted.

The retention clock starts when the media is stored, which is usually a few minutes after the meeting ends and processing finishes. Not when the bot joined, not when the call started.

## Set a default for your application

If 14 days isn't the right window for your app, set `retention_time` on your application configuration:

```bash
curl --request POST \
  --url 'https://api.us.nylas.com/v3/notetakers/configs' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "display_name": "Company defaults",
    "notetaker_settings": {
      "retention_time": 604800
    }
  }'
```

That's 7 days (604,800 seconds). Every Notetaker your app schedules from now on uses it. If you already have an application configuration, `PATCH` it with [`PATCH /v3/notetakers/configs/<CONFIG_ID>`](/docs/reference/api/notetaker-configurations/update-notetaker-config/); only the fields you send are touched.

## Different retention for one customer

A workspace configuration overrides the application default for every grant in that workspace. Reach for one when a single customer needs a different window, like a regulated customer that requires 90 days, or a trial customer you cap at 24 hours. For setting up the workspace itself, see [Notetaker configurations](/docs/v3/notetaker/configurations/#set-defaults-for-one-workspace).

```bash
curl --request POST \
  --url 'https://api.us.nylas.com/v3/notetakers/configs' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "workspace_id": "<WORKSPACE_ID>",
    "display_name": "Acme Sales",
    "notetaker_settings": {
      "retention_time": 7776000
    }
  }'
```

## Override on one Notetaker

To extend or shrink retention on a single recording, send `retention_time` on the Notetaker itself, either at create time or after.

```bash
curl --request PATCH \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "notetaker_settings": {
      "retention_time": 31536000
    }
  }'
```

That's a year. One thing worth knowing: the new expiration recalculates from when the media was originally stored, not from when you sent the PATCH. So extending from 7 days to a year on day 5 buys you 360 more days, not 365.

Shrinking works the same way with a smaller value. If the new expiration is already in the past, Nylas deletes the media on its next sweep, but it isn't instant. If you need media gone right now, use the DELETE endpoint below.

## Delete media immediately

If you need media gone before the retention window ends, [delete the Notetaker](/docs/v3/notetaker/#delete-a-notetaker). The `DELETE` endpoint removes the bot and all 5 possible files at once, and it's irreversible, so [download anything you want to keep](/docs/v3/notetaker/media-handling/#download-and-store-notetaker-media-files) first.

## Read the expiration back

The expiration timestamp shows up in three places:

- The first [`notetaker.media`](/docs/reference/notifications/notetaker/notetaker-media/) webhook (when media first becomes available) includes `retained_until` on the `media` object, a Unix timestamp.
- [`GET /v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>/media`](/docs/reference/api/notetaker/get-notetaker-media/) returns `expires_at` (Unix timestamp) and `ttl` (seconds remaining at the time of the request) for each file.
- [`GET /v3/notetakers/configs/<CONFIG_ID>`](/docs/reference/api/notetaker-configurations/get-notetaker-config/) returns the merged `notetaker_settings`, including `retention_time`.

## What happens at expiration

At the scheduled time, Nylas:

1. Deletes the recording, transcript, summary, action items, and thumbnail.
2. Sets the Notetaker's `state` and `status` to `media_deleted`.
3. Fires one final [`notetaker.media`](/docs/reference/notifications/notetaker/notetaker-media/) webhook with `status: media_deleted` and no `media` object.

After that, the [media endpoint](/docs/reference/api/notetaker/get-notetaker-media/) returns `410 Gone` with the body `media deleted`.

Only the media is deleted. The Notetaker record itself (state history, timestamps, original settings) stays around indefinitely.