--- title: "Retrieve a conversation" method: GET path: "/conversations/{id}" tags: ["Conversations"] --- # Retrieve a conversation `GET /conversations/{id}` ## Request - Base URL: `https://www.happyscribe.com/api/v1` - URL: `https://www.happyscribe.com/api/v1/conversations/{id}` - Auth: API key in header `Authorization` Retrieves metadata about a specific conversation. To retrieve the transcript content, use Exports. `audio_url`, `video_url`, and `soundwave_url` are signed URLs available once the media has been transcoded (state `automatic_done`); they expire after a short period, so fetch them fresh rather than caching. Conversations produced by the notetaker bot include a `meeting` object with calendar-aware metadata; it is `null` for uploaded files. ## Path parameters - `id` string, required ## Response `200` The conversation. - Conversation - `id` string: Unique identifier of the conversation. - `name` string - `folder` Folder - `id` integer - `name` string - `created_at` string, date-time - `updated_at` string, date-time - `state` 'initial' | 'ingesting' | 'automatic_transcribing' | 'automatic_done' | 'aligning' | 'locked' | 'failed' | 'demo': Current processing state: - `initial` — waiting to be processed - `ingesting` — media file is being ingested - `automatic_transcribing` — audio is being transcribed to text - `automatic_done` — finished and ready to export - `aligning` — text is being realigned with the audio - `locked` — locked due to insufficient credits - `failed` — file failed to process - `demo` — the initial demo file - `sharing_enabled` boolean: `true` when "Anyone with the link" is enabled. - `public_url` string, nullable: Public, no-login URL to share when `sharing_enabled` is `true`; `null` while sharing is disabled. - `language` string: BCP-47 language code. - `audio_length_in_seconds` number - `cost_in_cents` integer - `refunded` boolean - `tags` string[] - `delivery_estimated_at` string, date-time: Estimated delivery time. It can change over time. - `failure_reason` string, nullable: Error code for the failure. - `failure_message` string, nullable: User-friendly message explaining the failure root cause. - `soundwave_url` string, nullable: Soundwave in BBC audiowaveform binary format. Available once the state is `automatic_done`. - `audio_url` string, nullable: Short-lived signed URL to the transcoded MP3. Present once transcoded; fetch fresh rather than caching. - `video_url` string, nullable: Short-lived signed URL to the transcoded MP4. Present for video conversations once transcoded. - `meeting` MeetingMetadata: Calendar-aware metadata on conversations produced by the notetaker bot. For on-demand bot recordings (triggered manually rather than via a calendar invite), the bot-derived fields are populated while the calendar-derived fields are `null`. - `title` string: Original calendar event title; falls back to the bot-detected meeting name. - `url` string: The meeting join URL. - `platform` 'zoom' | 'google_meet' | 'microsoft_teams', nullable - `start_time` string, date-time, nullable: Scheduled start. `null` for on-demand recordings. - `end_time` string, date-time, nullable: Scheduled end. `null` for on-demand recordings. - `ical_uid` string, nullable: Standard iCalendar UID — the same value across all instances of a recurring series. Use it to join at the series level. - `calendar_event_id` string, nullable: Per-instance calendar event ID. Use it to join at the single-instance level. - `calendar_id` string, nullable: Identifier of the calendar the event belongs to. - `recurrent` boolean, nullable: `true` if the event is part of a recurring series. - `calendar_owner_role` 'organizer' | 'participant', nullable: Whether the connected calendar's member organized the meeting or participated. - `organizer` MeetingParticipant - `email` string: The participant's email. Used to name speakers. - `name` string, nullable: Resolved from the calendar invite, anything supplied at creation, the names people displayed in the call, and the people the workspace already knows, keeping the fullest. Null when no source knew one. - `participants` MeetingParticipant[]: Everyone invited to the meeting, identical to the participants array on the meeting resource and on meeting webhooks. Meeting rooms and the notetaker itself are excluded. - `email` string: The participant's email. Used to name speakers. - `name` string, nullable: Resolved from the calendar invite, anything supplied at creation, the names people displayed in the call, and the people the workspace already knows, keeping the fullest. Null when no source knew one. - `summary_url` string: URL to fetch the AI-generated meeting summary. Omitted when no summary exists yet. - `people` Person[]: (Memory API, enrolled workspaces only) People linked to this conversation. - `id` integer: Unique identifier. - `name` string: Display name (typically first name + last initial, or first name alone). - `full_name` string: Full name when available. - `emails` string[]: All email addresses recorded for this person, in discovery order. - `primary_email` string: The first email address recorded for this person. Discovery order, not user preference. - `company` Company - `id` integer: Unique identifier. - `name` string: The company name. - `primary_domain` string: The primary web domain for the company. - `domains` string[]: All known domains, including `primary_domain`. - `industry` string, nullable: Industry classification from enrichment. - `employee_count` integer, nullable: Approximate number of employees from enrichment. - `founded_year` integer, nullable: Year founded. - `short_description` string, nullable: A one-line description. - `keywords` string[]: Keywords describing the company. - `city` string, nullable: Headquarters city. - `country` string, nullable: Headquarters country. - `website_url` string, nullable: The company website. - `linkedin_url` string, nullable: The company LinkedIn page. - `logo_url` string, nullable: The company logo. - `total_funding` number, nullable: Total funding raised in USD. May be `null` even when enrichment has run. - `annual_revenue` number, nullable: Estimated annual revenue in USD. May be `null` even when enrichment has run. - `latest_funding_stage` string, nullable: Most recent funding stage, e.g. `Series A`. May be `null` even when enrichment has run. - `created_at` string, date-time: When it was created, in ISO 8601. - `updated_at` string, date-time: When it last changed, in ISO 8601. - `_links` object: Links to related resources. - `self` object: This resource. - `url` string: The URL. - `job_title` string, nullable: From enrichment. Person enrichment is disabled by default — typically `null`. - `seniority` string, nullable: From enrichment. Typically `null` unless person enrichment is enabled. - `headline` string, nullable: From enrichment. Typically `null` unless person enrichment is enabled. - `linkedin_url` string, nullable: From enrichment. Typically `null` unless person enrichment is enabled. - `city` string, nullable: From enrichment. Typically `null` unless person enrichment is enabled. - `country` string, nullable: From enrichment. Typically `null` unless person enrichment is enabled. - `photo_url` string, nullable: Full-size photo URL. - `avatar_url` string, nullable: Thumbnail avatar URL. - `enriched_at` string, date-time, nullable: Timestamp of the last enrichment run, or `null` if enrichment has not run. - `created_at` string, date-time: When it was created, in ISO 8601. - `updated_at` string, date-time: When it last changed, in ISO 8601. - `_links` object: Links to related resources. - `self` object: This resource. - `url` string: The URL. - `companies` Company[]: (Memory API, enrolled workspaces only) The distinct companies of those people. - `id` integer: Unique identifier. - `name` string: The company name. - `primary_domain` string: The primary web domain for the company. - `domains` string[]: All known domains, including `primary_domain`. - `industry` string, nullable: Industry classification from enrichment. - `employee_count` integer, nullable: Approximate number of employees from enrichment. - `founded_year` integer, nullable: Year founded. - `short_description` string, nullable: A one-line description. - `keywords` string[]: Keywords describing the company. - `city` string, nullable: Headquarters city. - `country` string, nullable: Headquarters country. - `website_url` string, nullable: The company website. - `linkedin_url` string, nullable: The company LinkedIn page. - `logo_url` string, nullable: The company logo. - `total_funding` number, nullable: Total funding raised in USD. May be `null` even when enrichment has run. - `annual_revenue` number, nullable: Estimated annual revenue in USD. May be `null` even when enrichment has run. - `latest_funding_stage` string, nullable: Most recent funding stage, e.g. `Series A`. May be `null` even when enrichment has run. - `created_at` string, date-time: When it was created, in ISO 8601. - `updated_at` string, date-time: When it last changed, in ISO 8601. - `_links` object: Links to related resources. - `self` object: This resource. - `url` string: The URL. - `speakers` Speaker[], nullable: The distinct speakers of the transcript, each tied to the Person resolved for that label. Returned by `GET /conversations/{id}` only. `null` until the transcript is ready. - `label` string: The exact string used in `transcript[].speaker`. - `name` string, nullable: The identified person's name. `null` when the label is not linked to a person. - `email` string, nullable: The identified person's email, or `null`. - `person_id` integer, nullable: A stable id for the identified person across meetings, or `null`. - `identified` boolean: `true` only when Voice ID linked the label to a person in the workspace. A label that merely reads like a name is not identified, and a workspace with no Voice ID links yet has every speaker unidentified. - `talk_time_seconds` number: Seconds of the transcript attributed to this speaker. - `_links` object - `self` object - `editor_url` string - `download_url` string ## Other responses - `401`: Your API key is missing (`missing_api_key`) or wrong (`invalid_api_key`), or it may not access this resource (`unauthorized`). - `404`: The specified resource could not be found, or this key cannot see it (`not_found`). --- [API](https://skmtc.dev/happyscribe/apis/happyscribe-api.md) - [All operations](https://skmtc.dev/happyscribe/apis/happyscribe-api/llms.txt) - [OpenAPI document](https://skmtc.dev/happyscribe/apis/happyscribe-api/revisions/1281bd968c3d?raw)