---
title: "Return Notetaker history"
method: GET
path: "/v3/grants/{grant_id}/notetakers/{notetaker_id}/history"
tags: ["Notetaker"]
---

# Return Notetaker history

`GET /v3/grants/{grant_id}/notetakers/{notetaker_id}/history`

## Request

- Base URL: `https://api.us.nylas.com`
- URL: `https://api.us.nylas.com/v3/grants/{grant_id}/notetakers/{notetaker_id}/history`
- Auth: HTTP bearer

Returns the full history of events and state changes for the specified Notetaker bot.

## Response `200`

Success. Returns Notetaker bot history events.

- object
  - `request_id` string: The request ID.
  - `data` object: The response object.
    - `events` NotetakerHistoryEvent[]: A list of Notetaker history events, ordered by most recent first.
      - `created_at` integer: When this history event was recorded, in seconds using the Unix timestamp format.
      - `event_type` 'notetaker.created' | 'notetaker.updated' | 'notetaker.meeting_state' | 'notetaker.media' | 'notetaker.deleted': The type of history event.
      - `data` object: The Notetaker bot payload at the time of the event.
        - `grant_id` string: The ID of the grant associated with this Notetaker bot.
        - `id` string: The Notetaker ID.
        - `join_time` integer: When Notetaker joined the meeting, in seconds using the Unix timestamp format.
        - `meeting_link` string: The meeting link.
        - `meeting_provider` 'Google Meet' | 'Zoom Meeting' | 'Microsoft Teams': The meeting provider.
        - `config_id` string: The ID of the configuration governing this Notetaker, if any.
        - `notetaker_settings` NotetakerSettings: Flat Notetaker settings for the configuration system. Omitted fields inherit from the parent configuration. After inheritance, dependency rules determine effective settings: summary and action_items require transcription. Nylas captures effective settings at dispatch; later parent edits do not rewrite an existing run's snapshot. Cannot be used together with the legacy `name` and `meeting_settings` fields.
          - `name` string: The display name shown when the Notetaker joins a meeting.
          - `recording_type` 'audio_video' | 'audio': What Notetaker records. `audio_video` produces an MP4 recording of the meeting's video and audio. `audio` produces an MP3 audio-only recording and does not capture video. Transcription, summaries, and action items work with either value. When no level of the configuration hierarchy sets it, Notetaker records audio and video.
          - `transcription` boolean: When `true`, Notetaker transcribes the meeting's audio.
          - `transcription_settings` object, nullable: Optional settings that tune how Notetaker transcribes audio. `transcription` must be `true` for these settings to take effect. Provide any combination of the fields below. The fields fall into two independent groups: - **Language hints** (`expected_languages`, `fallback_language`) constrain automatic language detection. This declares the languages you expect; it does not translate transcripts or force the recording into a specific language. - **Keyword hints** (`keywords`, `use_speaker_names_as_keywords`) bias recognition toward domain-specific terms such as names, acronyms, and product names. Set on individual Notetakers, on calendar sync, on event sync, or on a configuration. When set on a configuration or calendar, scheduled Notetakers inherit the value unless the request overrides it. Send `null` or `{}` to clear inherited settings and return to default transcription behavior. See [Set transcription languages](/docs/v3/notetaker/transcription-settings/) for supported language codes and validation rules.
            - `expected_languages` string[]: Language codes the audio is expected to contain. Optional. When provided, it must contain at least one supported code and cannot be `null` or empty. When omitted, transcription considers all supported languages.
            - `fallback_language` string: Language to use if Notetaker does not detect one of the `expected_languages`. Optional. When `expected_languages` is set, the fallback must be one of those codes. When `expected_languages` is omitted, transcription considers all supported languages and the fallback may be any supported code. When `fallback_language` is omitted, the transcriber auto-detects the language. The field is not stored, so responses do not return it.
            - `keywords` string[]: Domain-specific terms that bias transcription toward recognizing them correctly, such as names, acronyms, and product names. Optional. All terms together can contain up to 200 words, and each term can contain up to 6 words. Words are separated by spaces, so `Nylas` uses 1 word and `Jane Doe` uses 2. Each term must also be 1 to 200 characters and cannot contain control characters. Cannot be `null`.
            - `use_speaker_names_as_keywords` boolean: When `true`, Notetaker adds known speaker names to the keyword set so they are transcribed accurately. Optional. Cannot be `null`.
          - `summary` boolean: When `true`, Notetaker generates a summary of the meeting. Requires `transcription` to also be `true`.
          - `summary_settings` object
            - `custom_instructions` string: Custom instructions for the AI summary model.
          - `action_items` boolean: When `true`, Notetaker generates a list of action items. Requires `transcription` to also be `true`.
          - `action_items_settings` object
            - `custom_instructions` string: Custom instructions for the AI action items model.
          - `leave_after_silence_seconds` integer: Seconds of continuous silence after which the Notetaker automatically leaves the meeting. Must be between 10 and 3600 seconds (1 hour).
          - `messages` Messages: Custom announcements the Notetaker bot posts to the meeting chat. Use this to greet attendees when the bot joins, or to acknowledge new participants as they arrive. Messages are optional; when omitted, the bot only posts the default recording-and-transcription notice described in [Using Nylas Notetaker](/docs/v3/notetaker/). Like other `notetaker_settings` fields, `messages` participates in the configuration hierarchy and uses whole-object override semantics: the most specific layer that sets `messages` completely replaces the parent's value (there is no per-message merging). See [Custom announcements](/docs/v3/notetaker/custom-announcements/) for the full inheritance model.
            - `on_join` OnJoinMessage[]: Messages the bot sends shortly after it joins the meeting. Each message has its own configurable delay measured from the moment the bot joins. Up to 10 messages per trigger.
              - …
            - `on_participant_join` OnParticipantJoinMessage[]: Messages the bot sends when a new participant joins the meeting. Each message uses a trailing debounce window — if another participant joins before the window expires, the timer resets and only one message is posted per burst of joins. Up to 10 messages per trigger.
              - …
          - `video_output` VideoOutput: A static image the Notetaker bot shows as its camera feed when it joins a meeting, instead of a blank tile. Sometimes called the bot avatar. Supported on Google Meet, Microsoft Teams, and Zoom; on other providers the bot joins without showing the image. Author images at a 16:9 aspect ratio. Text in the image appears mirrored in the recording. Upload the image in one of two ways: - **Multipart** (recommended): send the request as `multipart/form-data` and set `file_key` to the name of the file part that contains the image. The JSON part must be named `config` on the configuration endpoints and `notetaker` on the Notetaker endpoints. File parts up to 4 MiB. - **JSON + base64**: send `media_type` and `data` together on a plain `application/json` request. The decoded image must be 1,376,256 bytes (about 1.31 MB) or smaller. Accepted formats are PNG, JPEG, and static WebP, up to 3840x2160 pixels and no more than 8,294,400 total pixels. The format is detected from the file content, not the declared content type. On `PATCH`, omitting `video_output` preserves the existing image, sending a new image replaces it, and sending an empty object (`{}`) disables video output at that layer. Accepted when you create or update a configuration or a Notetaker. Not supported on calendar sync or event sync requests. See [Notetaker custom video output](/docs/v3/notetaker/custom-video-output/).
            - `file_key` string: The name of the multipart file part that contains the image. Only valid on `multipart/form-data` requests, must reference exactly one file part, and cannot be combined with `media_type` or `data`.
            - `media_type` 'image/png' | 'image/jpeg' | 'image/webp': The image MIME type. On a JSON write, required together with `data` and must match the actual file content. Always returned in responses.
            - `data` string, byte: The base64-encoded image bytes. Only valid on `application/json` requests, required together with `media_type`, and must decode to 1,376,256 bytes or smaller.
            - `size` integer: The stored image size in bytes. Read-only; rejected on writes.
            - `preview_url` string: A signed URL for previewing the stored image. Valid for 1 hour; fetch the configuration again to get a fresh URL. Read-only; rejected on writes.
            - `preview_url_expires_at` integer: When `preview_url` expires, as a Unix timestamp in seconds. Read-only; rejected on writes.
          - `retention_time` integer: How long Notetaker media (recording, transcript, summary, action items, and thumbnail) is kept before Nylas automatically deletes it, in seconds. Must be between 300 and 2,592,000 seconds (5 minutes to 30 days). The clock starts when the media is first stored after the meeting ends. Defaults to 1,209,600 seconds (14 days). Nylas resolves the effective value from the configuration hierarchy each time it checks for expiration, so changing it on an application or workspace configuration also re-times existing media that inherits it. Setting it on a single Notetaker overrides the configuration for that bot, and can only be changed while the Notetaker is still scheduled.
        - `meeting_settings` MeetingSettings: A collection of settings for the Notetaker bot.
          - `action_items` boolean: When `true`, Notetaker generates a list of action items from the meeting. If `action_items` is `true`, `video_recording`, `audio_recording`, and `transcription` must also be `true`.
          - `action_items_settings` object
            - `custom_instructions` string: A custom prompt to pass to Nylas' AI model and specify settings for the list of action items it generates. `action_items` must be `true` to use this field.
          - `audio_recording` boolean: When `true`, Notetaker records the meeting's audio.
          - `leave_after_silence_seconds` integer: The number of seconds of silence after which the Notetaker bot automatically leaves the meeting. This helps end recordings when meetings have concluded but participants haven't disconnected the call. Must be between 10 and 3600 seconds (1 hour).
          - `summary` boolean: When `true`, Notetaker generates a summary of the meeting. If `summary` is `true`, `video_recording`, `audio_recording`, and `transcription` must also be `true`.
          - `summary_settings` object
            - `custom_instructions` string: A custom prompt to pass to Nylas' AI model and specify settings for the summary it generates. `summary` must be `true` to use this field.
          - `transcription` boolean: When `true`, Notetaker transcribes the meeting's audio. If `transcription` is `true`, `video_recording` and `audio_recording` must also be `true`.
          - `video_recording` boolean: When `true`, Notetaker records the meeting's video.
          - `transcription_settings` object, nullable: Optional settings that tune how Notetaker transcribes audio. `transcription` must be `true` for these settings to take effect. Provide any combination of the fields below. The fields fall into two independent groups: - **Language hints** (`expected_languages`, `fallback_language`) constrain automatic language detection. This declares the languages you expect; it does not translate transcripts or force the recording into a specific language. - **Keyword hints** (`keywords`, `use_speaker_names_as_keywords`) bias recognition toward domain-specific terms such as names, acronyms, and product names. Set on individual Notetakers, on calendar sync, or on event sync. When set on a calendar, events inherit the value unless the event's own request overrides it. Send `null` or `{}` to clear inherited settings and return to default transcription behavior. See [Set transcription languages](/docs/v3/notetaker/transcription-settings/) for supported language codes and validation rules.
            - `expected_languages` string[]: Language codes the audio is expected to contain. Optional. When provided, it must contain at least one supported code and cannot be `null` or empty. When omitted, transcription considers all supported languages.
            - `fallback_language` string: Language to use if Notetaker does not detect one of the `expected_languages`. Optional. When `expected_languages` is set, the fallback must be one of those codes. When `expected_languages` is omitted, transcription considers all supported languages and the fallback may be any supported code. When `fallback_language` is omitted, the transcriber auto-detects the language. The field is not stored, so responses do not return it.
            - `keywords` string[]: Domain-specific terms that bias transcription toward recognizing them correctly, such as names, acronyms, and product names. Optional. All terms together can contain up to 200 words, and each term can contain up to 6 words. Words are separated by spaces, so `Nylas` uses 1 word and `Jane Doe` uses 2. Each term must also be 1 to 200 characters and cannot contain control characters. Cannot be `null`.
            - `use_speaker_names_as_keywords` boolean: When `true`, Notetaker adds known speaker names to the keyword set so they are transcribed accurately. Optional. Cannot be `null`.
          - `messages` Messages: Custom announcements the Notetaker bot posts to the meeting chat. Use this to greet attendees when the bot joins, or to acknowledge new participants as they arrive. Messages are optional; when omitted, the bot only posts the default recording-and-transcription notice described in [Using Nylas Notetaker](/docs/v3/notetaker/). Like other `notetaker_settings` fields, `messages` participates in the configuration hierarchy and uses whole-object override semantics: the most specific layer that sets `messages` completely replaces the parent's value (there is no per-message merging). See [Custom announcements](/docs/v3/notetaker/custom-announcements/) for the full inheritance model.
            - `on_join` OnJoinMessage[]: Messages the bot sends shortly after it joins the meeting. Each message has its own configurable delay measured from the moment the bot joins. Up to 10 messages per trigger.
              - …
            - `on_participant_join` OnParticipantJoinMessage[]: Messages the bot sends when a new participant joins the meeting. Each message uses a trailing debounce window — if another participant joins before the window expires, the timer resets and only one message is posted per burst of joins. Up to 10 messages per trigger.
              - …
        - `name` string: The display name for the Notetaker bot.
        - `object` string: The type of object.
        - `state` 'scheduled' | 'connecting' | 'waiting_for_entry' | 'attending' | 'disconnected' | 'worker_finished' | 'processing' | 'available' | 'media_error' | 'media_deleted' | 'failed_entry': The current state of the Notetaker bot.
        - `status` string: The current status of the Notetaker bot.
        - `meeting_state` string: Additional information about the Notetaker bot's meeting state for `notetaker.meeting_state` events. The value depends on the current `state`: When `state` is `connecting`: `waiting_for_entry`. When `state` is `attending`: `recording_active`. When `state` is `disconnected`: `meeting_ended`, `kicked`, `no_activity`, `no_participants`, `api_request`, `network_error`, `cancelled`, `unknown`. When `state` is `failed_entry`: `error`, `internal_error`, `bad_meeting_code`, `bad_meeting_link`, `sign_in_required`, `entry_denied`, `no_response`, `cannot_join`, `meeting_capacity_reached`, `admission_timeout`, `network_error`, `cancelled`. When `state` is `worker_finished`: `worker_finished`.
        - `media` object: Media files generated by the Notetaker bot for `notetaker.media` events.
          - `recording` string: A URL to the meeting recording file.
          - `recording_duration` string: The duration of the recording, in seconds.
          - `transcript` string: A URL to the meeting transcript file.
          - `thumbnail` string: A URL to a thumbnail image from the recording.
          - `summary` string: A URL to a summary file generated from the meeting.
          - `action_items` string: A URL to an action items file generated from the meeting.
        - `event` object: Information about the calendar event associated with this Notetaker bot, if applicable.
          - `event_id` string: The associated Nylas event ID.
          - `ical_uid` string: The iCalendar UID of the event.
          - `master_event_id` string: The master event ID for recurring events, if applicable.

## Other responses

- `401`: Unauthorized
- `404`: Not Found
- `429`: Rate limited. The provider or Nylas throttled the request. If a provider throttles a request and says how long to wait, the `Retry-After` header gives that number of seconds. When the header is missing, retry with exponential backoff. See [429 rate limit errors by provider](/docs/api/errors/400-response/#429-rate-limit-errors-by-provider).

## Changes

- **2026-09-26** `763d6b969cd7`: 1 info
  - added the optional property `error/provider_error` to the response with the `429` status
- **2026-09-22** `a0f9c939b823`: 4 info
  - added the optional property `allOf[subschema #2]/data/events/items/data/allOf[#/components/schemas/notetaker]/config_id` to the response with the `200` status
  - added the optional property `allOf[subschema #2]/data/events/items/data/allOf[#/components/schemas/notetaker]/meeting_settings/allOf[subschema #2]/messages` to the response with the `200` status
  - added the optional property `allOf[subschema #2]/data/events/items/data/allOf[#/components/schemas/notetaker]/notetaker_settings` to the response with the `200` status
  - response property `allOf[subschema #2]/data/events/items/data/allOf[#/components/schemas/notetaker]/meeting_settings` deprecated

[Operation history](https://skmtc.dev/nylas/apis/nylas-api/changes/v3/grants/:grant_id/notetakers/:notetaker_id/history/get.md)

---

[API](https://skmtc.dev/nylas/apis/nylas-api.md) - [All operations](https://skmtc.dev/nylas/apis/nylas-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nylas/apis/nylas-api/revisions/7782a3e3ab70?raw)