Skip to content
Skip to main content

Using Notetaker retention policies

Last updated:

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 allowed range is 300 to 2,592,000 seconds (5 minutes to 30 days).

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.

Notetaker media retention timeline

The retention clock starts when Nylas stores the media, not when the bot joins. When the retention window ends, Nylas deletes every file.
Diagram as text
  • Meeting ends: The bot leaves the meeting.
  • Processing media: Nylas builds the recording, transcript, and any summary or action items. (notetaker.media: processing)
  • Media available: The retention clock starts here. The webhook includes retained_until. (notetaker.media: available)
    • Changing retention: A configuration change re-times media that inherits it, counted from when the media was stored.
    • Changing retention: A single Notetaker's retention_time can change only while it's scheduled.
    • After 60 minutes → Download links expire: Request the media endpoint again for current links.
  • Retention window ends: retention_time is 300 to 2,592,000 seconds (5 minutes to 30 days). (retention_time elapses)
  • Media deleted: Nylas deletes every file. The webhook has no media object. (notetaker.media: media_deleted)
  • Media no longer available: GET /v3/grants/{grant_id}/notetakers/{notetaker_id}/media returns 410.

Minimum and maximum retention time

Section titled “Minimum and maximum retention time”

The minimum retention_time is 300 seconds (5 minutes) and the maximum is 2,592,000 seconds (30 days). The same limits apply everywhere you can set it: application and workspace configurations, and the notetaker_settings on a single Notetaker’s create or update request.

A value outside that range returns 400 Bad Request:

{
  "request_id": "<REQUEST_ID>",
  "error": {
    "type": "bad_request",
    "message": "retention_time must be between 300 and 2592000 seconds"
  }
}

retention_time must be a whole number. A string like "300" or a decimal like 300.5 also returns 400, but with the message malformed request body, so check the type first if you see that error. Sending null removes the value, and the Notetaker falls back to the next configuration up the configuration hierarchy, or the 14-day default if none sets one.

Set a default for your application

Section titled “Set a default for your application”

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

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

That’s 7 days (604,800 seconds). It applies to every Notetaker that doesn’t set its own retention_time, including ones that already have media (see Change retention for existing media). If you already have an application configuration, PATCH it with PATCH /v3/notetakers/configs/<CONFIG_ID>; only the fields you send are touched.

Different retention for one customer

Section titled “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 customer that needs 30 days, or a trial customer you cap at 24 hours. For setting up the workspace itself, see Notetaker configurations.

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": 2592000
    }
  }'

Override on one Notetaker

Section titled “Override on one Notetaker”

To give a single meeting a different window, send retention_time in notetaker_settings when you create the Notetaker with POST /v3/grants/<NYLAS_GRANT_ID>/notetakers. The value applies to that Notetaker only and overrides whatever its application or workspace configuration sets.

curl --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "meeting_link": "<MEETING_URL>",
    "notetaker_settings": {
      "retention_time": 2592000
    }
  }'

That’s 30 days. You can also change it with PATCH /v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>, but only while the Notetaker is still in the scheduled state. Once the bot joins the meeting, the update request returns 400 Bad Request with the message notetaker is not in scheduled state, and you can no longer change the per-Notetaker value.

Change retention for existing media

Section titled “Change retention for existing media”

Nylas doesn’t store the retention window on a finished recording. It resolves retention_time from the configuration hierarchy each time it checks for expiration, so updating an application or workspace configuration re-times every existing recording that inherits from it. The new expiration is always counted from when the media was first stored, not from when you made the change.

For example, if you raise a workspace configuration from 7 days to 30 days on day 5, media recorded on day 0 now expires on day 30, 25 days later. The expires_at value from the media endpoint reflects the new window on the next request, but the retained_until value in the original webhook doesn’t change.

Shrinking works the same way. If the new expiration is already in the past, Nylas deletes the media on its next sweep, but it isn’t instant.

Notetakers that set their own retention_time at create time keep it. A configuration change doesn’t move them, and there’s no way to change their window after the meeting. To remove that media early, delete the Notetaker.

Delete media immediately

Section titled “Delete media immediately”

If you need media gone before the retention window ends, delete the 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 first.

Read the expiration back

Section titled “Read the expiration back”

The expiration timestamp shows up in three places:

The webhook’s retained_until is a snapshot from when the webhook fired. Nylas sends it once and doesn’t send an update if you later change the configuration and re-time the media. Treat the media endpoint’s expires_at as the current value, and fetch it again after any retention change.

What happens at expiration

Section titled “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 webhook with status: media_deleted and no media object.

After that, the media endpoint 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.