A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Gong API is how an app or AI agent works with a Gong account: listing recorded calls, pulling their transcripts, reading activity stats for a team, or assigning prospects to an Engage flow. Access is granted through an access key and secret or an OAuth grant, and a set of granular scopes decides which areas a call can read or write. Gong analyzes conversations rather than just storing them, and it also runs a first-party server that hands an agent already-summarized account and deal insights.
How an app or AI agent connects to Gong determines what it can reach. There is a route for calling the API directly, and a hosted server that exposes Gong's analyzed insights to agents, and each is governed by the key or grant behind it and the permissions that key carries.
The v2 REST API serves JSON and pages through lists with a cursor. A call authenticates with an access key and secret sent as HTTP Basic auth, or with an OAuth 2.0 Bearer token whose granular scopes decide which areas it can read or write. For OAuth apps the base host varies per customer and is returned when the token is generated.
Gong runs a first-party Model Context Protocol server, announced in May 2026 and rolling out as a preview from June 2026. It exposes read-only tools that return AI-synthesized insights rather than raw data, like ask_account and ask_deal for natural-language questions about an account or deal, and generate_brief for a structured summary across themes, stakeholders, risks, and next steps. It authenticates with OAuth 2.0 using the authorization-code flow with PKCE, and supports both personal and shared access.
An administrator generates an access key and secret in Gong's API settings. The two are combined and sent as an HTTP Basic auth header on every request. This key carries the access of the account it was created under, so it is kept server-side and never exposed in client code.
An app sends the account through Gong's authorize URL, then exchanges the returned authorization code for a Bearer access token at the token endpoint. The app requests granular scopes up front, and the token can only call the areas those scopes cover. Gong authenticates OAuth once at the account level rather than per individual user, and the API base host for the customer is returned with the token.
The Gong API is split into areas an agent can act on, like recorded calls, transcripts, users, customer-relationship data, activity stats, and Engage flows. Each area has its own methods, and a few write to real records, like uploading a call or erasing a person's data.
Methods for listing, retrieving, uploading, and managing recorded calls.
Methods for retrieving the spoken transcript of calls.
Methods for reading the user directory and the company's workspaces.
Methods for the Generic CRM integration: objects, schema, and status.
Methods for activity, interaction, and scorecard statistics.
Methods for reading library folders and their call content.
Methods for Gong Engage: listing flows and assigning prospects.
Methods for reporting content views, shares, and custom actions into Gong.
Methods for creating, updating, and deleting Gong meetings.
Methods for finding and erasing a person's data by email or phone.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
CallsMethods for listing, retrieving, uploading, and managing recorded calls.6 | ||||||
| GET | /v2/calls | List basic data for calls that took place in a given date range. | read | api:calls:read:basic | Current | |
Returns lightweight call records; richer detail comes from the extensive method. Acts oncall Permission (capability) api:calls:read:basicVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/calls/{id} | Retrieve basic data for a specific call by its ID. | read | api:calls:read:basic | Current | |
Read-only. Acts oncall Permission (capability) api:calls:read:basicVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/calls/extensive | List detailed call data filtered by date range, call IDs, or hosting users. | read | api:calls:read:extensive | Current | |
Returns richer detail than the basic list, like parties, context, and content. Read-only despite the POST verb, which carries the filter body. Acts oncall Permission (capability) api:calls:read:extensiveVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/calls | Add a new call to Gong, registering its metadata. | write | api:calls:create | Current | |
Creates a real call record; media is added separately. Acts oncall Permission (capability) api:calls:createVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v2/calls/{id}/media | Attach the recording media to a previously added call. | write | api:calls:create | Current | |
Uploads the audio or video for a call created via the add-call method. Acts oncall Permission (capability) api:calls:createVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/calls/users-access | List the users who have been granted access to specific calls. | read | — | Current | |
Read-only. The exact scope is not stated on the public overview; verify in Gong's gated API reference. Acts oncall-access Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TranscriptsMethods for retrieving the spoken transcript of calls.1 | ||||||
| POST | /v2/calls/transcript | Retrieve transcripts of calls in a date range, optionally filtered to specific call IDs. | read | api:calls:read:transcript | Current | |
Separate scope from basic call data, so a token can read summaries without the full conversation. Read-only despite the POST verb. Acts ontranscript Permission (capability) api:calls:read:transcriptVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Users & WorkspacesMethods for reading the user directory and the company's workspaces.4 | ||||||
| GET | /v2/users | List all users in the company. | read | api:users:read | Current | |
Read-only directory access. Acts onuser Permission (capability) api:users:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/users/{id} | Retrieve a specific user by ID. | read | api:users:read | Current | |
Read-only. Acts onuser Permission (capability) api:users:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/users/extensive | List users filtered by criteria such as a set of user IDs. | read | api:users:read | Current | |
Read-only despite the POST verb, which carries the filter body. Acts onuser Permission (capability) api:users:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/workspaces | List all of the company's workspaces. | read | api:users:read | Current | |
Read-only. Returns the workspaces that organize calls and users. Acts onworkspace Permission (capability) api:users:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CRMMethods for the Generic CRM integration: objects, schema, and status.3 | ||||||
| GET | /v2/crm/object/list | List CRM objects held in the Generic CRM integration. | read | — | Current | |
Read-only. The exact CRM scope string is not stated on the public overview; verify in Gong's gated API reference. Acts oncrm-object Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/crm/object/entities | Upload CRM object records into the Generic CRM integration. | write | — | Current | |
Writes CRM records. The exact CRM scope string is not stated on the public overview; verify in Gong's gated API reference. Acts oncrm-object Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/crm/object/schema/list | List the schema fields for a CRM object type in the Generic CRM integration. | read | — | Current | |
Read-only. The exact CRM scope string is not stated on the public overview; verify in Gong's gated API reference. Acts oncrm-schema Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
StatsMethods for activity, interaction, and scorecard statistics.5 | ||||||
| POST | /v2/stats/interaction | Retrieve interaction statistics for users over a date range. | read | api:stats:interaction | Current | |
Read-only despite the POST verb, which carries the filter body. Acts onstat Permission (capability) api:stats:interactionVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/stats/activity/aggregate | Retrieve aggregated activity stats for users over a date range. | read | — | Current | |
Read-only. The exact activity-stats scope is not stated on the public overview; verify in Gong's gated API reference. Acts onstat Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/stats/activity/day-by-day | Retrieve day-by-day activity stats for users over a date range. | read | — | Current | |
Read-only. The exact activity-stats scope is not stated on the public overview; verify in Gong's gated API reference. Acts onstat Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/stats/activity/scorecards | Retrieve answered scorecard reviews over a date range. | read | api:stats:scorecards | Current | |
Read-only despite the POST verb, which carries the filter body. Acts onscorecard Permission (capability) api:stats:scorecardsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/settings/scorecards | Retrieve the configured scorecards and their questions. | read | api:settings:scorecards:read | Current | |
Read-only. Acts onscorecard Permission (capability) api:settings:scorecards:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
LibraryMethods for reading library folders and their call content.2 | ||||||
| GET | /v2/library/folders | Retrieve the list of public library folders. | read | — | Current | |
Read-only. The exact library scope is not stated on the public overview; verify in Gong's gated API reference. Acts onlibrary-folder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/library/folder-content | List the calls saved inside a specific library folder. | read | — | Current | |
Read-only. The exact library scope is not stated on the public overview; verify in Gong's gated API reference. Acts onlibrary-folder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Engage flowsMethods for Gong Engage: listing flows and assigning prospects.4 | ||||||
| GET | /v2/flows | List Gong Engage flows. | read | api:flows:read | Current | |
Read-only. Acts onflow Permission (capability) api:flows:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/flows/folders | List Engage flow folders and their visibility types. | read | api:flows:read | Current | |
Read-only. Acts onflow-folder Permission (capability) api:flows:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/flows/prospects/assign | Assign prospects to an Engage flow, optionally configuring its steps. | write | api:flows:write | New | |
Enrolls prospects in outreach. Step configuration on assignment was added in September 2025. Acts onflow-assignment Permission (capability) api:flows:writeVersionIntroduced 2025-09-01 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/flows/prospects/unassign-flows-by-crm-id | Remove prospects from Engage flows, identified by CRM ID. | write | api:flows:write | Current | |
Removes prospects from outreach flows. Acts onflow-assignment Permission (capability) api:flows:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Customer engagementMethods for reporting content views, shares, and custom actions into Gong.2 | ||||||
| PUT | /v2/customer-engagement/content/viewed | Report that a piece of shared content was viewed. | write | — | Current | |
Records an engagement event into Gong. The exact engagement scope is not stated on the public overview; verify in Gong's gated API reference. Acts onengagement-event Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v2/customer-engagement/action | Report a custom engagement action against a contact. | write | — | Current | |
Records an engagement event into Gong. The exact engagement scope is not stated on the public overview; verify in Gong's gated API reference. Acts onengagement-event Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
MeetingsMethods for creating, updating, and deleting Gong meetings.3 | ||||||
| POST | /v2/meetings | Create a new Gong meeting. | write | api:meetings:user:create | Current | |
Creates a real scheduled meeting. Acts onmeeting Permission (capability) api:meetings:user:createVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v2/meetings/{meetingId} | Update an existing Gong meeting. | write | api:meetings:user:update | Current | |
Changes a real scheduled meeting. Acts onmeeting Permission (capability) api:meetings:user:updateVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/meetings/{meetingId} | Delete a Gong meeting. | write | api:meetings:user:update | Current | |
Permanently removes a scheduled meeting. Acts onmeeting Permission (capability) api:meetings:user:updateVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Data privacyMethods for finding and erasing a person's data by email or phone.2 | ||||||
| GET | /v2/data-privacy/data-for-email-address | Find references to a given email address across Gong data. | read | — | Current | |
Read-only. The exact data-privacy scope is not stated on the public overview; verify in Gong's gated API reference. Acts onprivacy-record Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/data-privacy/erase-data-for-email-address | Permanently delete a given email address and its associated data. | write | — | Current | |
Irreversible deletion of a person's data. The exact data-privacy scope is not stated on the public overview; verify in Gong's gated API reference. Acts onprivacy-record Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Gong does not publish a general webhook system for the public API. An integration reads activity by calling the API on a schedule rather than receiving pushed events, and reports engagement events back into Gong through the customer-engagement methods.
| Event | What it signals | Triggered by |
|---|
Gong limits how fast and how much an app can call, by a per-second request rate and a separate daily ceiling that apply across the account.
Gong meters requests by a fixed rate, not by a per-method cost. An account is allowed 3 requests per second and 10,000 requests per day, shared across every key on the account. Going over either limit returns HTTP 429 with a Retry-After header that names how many seconds to wait before retrying. The daily ceiling can be raised on request through Gong support.
A list method returns results in pages and includes a records object with a cursor when more results remain. The next request passes that cursor to fetch the following page. A cursor is short-lived, so the next page should be fetched promptly rather than held.
Page sizes are fixed by the endpoint rather than set by the caller, and large pulls are walked through with the cursor. Bulk reads like extensive call data and transcripts are filtered by a date range and optional call-id list to keep each request bounded.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request was malformed, like a missing required filter or an invalid date range on a list or extensive call. | Read the error body, fix the parameters, and resend. The request is not retryable as-is. |
| 401 | Unauthorized | No valid credentials were supplied, like a wrong access key and secret or an expired or missing Bearer token. | Confirm the access key and secret, or refresh the OAuth token, and resend. |
| 403 | Forbidden | The credentials are valid but lack the scope or permission the request needs, like calling a transcript method without api:calls:read:transcript. | Grant the matching scope on the OAuth app, or use a key with the needed permission. |
| 404 | Not Found | The requested object does not exist or is not visible to this account, like an unknown call or user ID. | Verify the ID and that it belongs to the same account. |
| 429 | Too Many Requests | The per-second or daily rate limit was exceeded. | Wait the number of seconds named in the Retry-After header, then retry, and smooth the request rate. |
| 500 | Internal Server Error | An error on Gong's side. It is rare. | Retry with backoff, and contact Gong support if it persists. |
Gong serves a single dated API under one path version, and announces notable changes through its release notes, giving at least 30 days notice before a breaking change.
Gong serves a single dated API under the v2 path. Notable changes ship through the release notes rather than a new path version, and Gong commits to announcing a breaking change at least 30 days in advance.
Gong announced first-party MCP support, letting external AI agents reach Gong's analyzed account and deal insights, and letting Gong's own agents call out to external MCP servers.
The flow-assignment method was extended so an integration can configure flow steps at the moment it assigns prospects to a flow.
Track the release notes, since breaking changes are announced ahead of time.
Gong release notes ↗Bollard AI sits between a team's AI agents and Gong. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.