A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Pendo API is how an app or AI agent works with a Pendo subscription: querying product usage across visitors and accounts, reading and writing visitor and account metadata, and listing the features, pages, and guides being tracked. Access is granted through an integration key created at the subscription level, and that key carries a single read-only or read-write level rather than per-area permissions. Most reads run through one flexible aggregation query engine instead of many endpoints, and the API has no event push, so an app polls it for changes.
How an app or AI agent connects to Pendo determines what it can reach. There is a route for querying and updating product data with a static key, and a hosted server that exposes Pendo data to AI agents, and each is governed by the credential behind it and the level it carries.
The REST API takes JSON requests and returns JSON, authenticated with a static integration key in the x-pendo-integration-key header. US subscriptions call the host app.pendo.io and EU subscriptions call app.eu.pendo.io, both under the /api/v1 path. Most reads run through one aggregation method rather than many list endpoints, and writes are limited to setting custom visitor and account metadata.
Pendo runs a first-party, hosted Model Context Protocol server that exposes Pendo product data to AI clients like Claude, ChatGPT, Cursor, Gemini CLI, and Windsurf. It authenticates with OAuth and respects the connecting user's existing Pendo permissions, so an agent only reaches data that user is already authorized to see. It surfaces visitor and account metadata, product usage and analytics, page, feature, and track event data, and aggregation-style queries.
Pendo's REST API authenticates with a static integration key, created on the Integration Keys page by a Pendo admin and sent in the x-pendo-integration-key header. The key is designated read-only or read-write at creation, at the subscription level, with no finer per-endpoint scopes. It is not tied to one application and reaches every application in the subscription, and it does not expire on its own.
The first-party Pendo MCP server uses OAuth to connect an AI client to a user's Pendo account. The resulting access respects that user's existing Pendo permissions rather than carrying a separate scope, so an agent reaches only what the user can already see.
The Pendo API is split into areas an agent can act on, like querying product usage, reading and writing visitor and account metadata, and listing the features, pages, and guides being tracked. Most reads run through one query engine, and writes are limited to custom metadata fields.
The single query method for pulling product data: visitors, accounts, events, and feature, page, and guide usage.
Methods for reading a visitor record and setting its custom metadata.
Methods for reading an account record and setting its custom metadata.
Methods for listing and retrieving the features, pages, and guides being tracked in a subscription.
Methods for reading the schema of visitor and account metadata fields.
Methods for running a saved visitor or account report and pulling its results.
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 | |
|---|---|---|---|---|---|---|
Aggregation (query engine)The single query method for pulling product data: visitors, accounts, events, and feature, page, and guide usage.1 | ||||||
| POST | /api/v1/aggregation | Run an aggregation pipeline to query visitors, accounts, events, and feature, page, or guide usage. | read | read | Current | |
The primary read method; a JSON pipeline names a source and applies operators to filter and shape rows. Reachable with a read-only key. Acts onaggregation Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
VisitorsMethods for reading a visitor record and setting its custom metadata.3 | ||||||
| GET | /api/v1/visitor/{visitorId} | Retrieve a single visitor record, including its metadata. | read | read | Current | |
Read-only. There is no paginated list of visitors; use the aggregation pipeline to pull many at once. Acts onvisitor Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/metadata/visitor/custom/value | Set custom metadata values on one or more visitors. | write | write | Current | |
Needs a read-write key. Only custom metadata fields can be written; auto and agent fields are managed by the install snippet. Append ?create=true to create records. Acts onvisitor Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/metadata/visitor/custom/value/bulk | Set custom metadata on many visitors in a single batched request. | write | write | Current | |
Needs a read-write key. Pendo recommends batching writes here rather than one record at a time, with batches kept under 1,000 records. Acts onvisitor Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AccountsMethods for reading an account record and setting its custom metadata.3 | ||||||
| GET | /api/v1/account/{accountId} | Retrieve a single account record, including its metadata. | read | read | Current | |
Read-only. Acts onaccount Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/metadata/account/custom/value | Set custom metadata values on one or more accounts. | write | write | Current | |
Needs a read-write key. Only custom metadata fields can be written. Append ?create=true to create records. Acts onaccount Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/metadata/account/custom/value/bulk | Set custom metadata on many accounts in a single batched request. | write | write | Current | |
Needs a read-write key. Pendo recommends batching account metadata writes here, with batches kept under 1,000 records. Acts onaccount Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Features, Pages & GuidesMethods for listing and retrieving the features, pages, and guides being tracked in a subscription.6 | ||||||
| GET | /api/v1/feature | List the features being tracked, optionally filtered to one application or expanded across all. | read | read | Current | |
Read-only. Add ?appId={id} to scope to one application, or ?expand=* to cover every application in the subscription. Acts onfeature Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/feature/{featureId} | Retrieve the details of a single tracked feature. | read | read | Current | |
Read-only. Acts onfeature Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/page | List the pages being tracked, optionally filtered to one application or expanded across all. | read | read | Current | |
Read-only. Add ?appId={id} to scope to one application, or ?expand=* to cover every application. Acts onpage Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/page/{pageId} | Retrieve the details of a single tracked page. | read | read | Current | |
Read-only. Acts onpage Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/guide | List the guides in the subscription, optionally filtered to one application or expanded across all. | read | read | Current | |
Read-only. Add ?appId={id} to scope to one application, or ?expand=* to cover every application. Acts onguide Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/guide/{guideId} | Retrieve the details of a single guide, including its content and steps. | read | read | Current | |
Read-only. Acts onguide Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Metadata schemaMethods for reading the schema of visitor and account metadata fields.2 | ||||||
| GET | /api/v1/metadata/schema/visitor | Retrieve the schema of visitor metadata fields, including names and types. | read | read | Current | |
Read-only. Returns the configured visitor fields and their data types (text, number, boolean, date). Acts onmetadata_schema Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/metadata/schema/account | Retrieve the schema of account metadata fields, including names and types. | read | read | Current | |
Read-only. Returns the configured account fields and their data types. Acts onmetadata_schema Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ReportsMethods for running a saved visitor or account report and pulling its results.2 | ||||||
| GET | /api/v1/report/{reportId}/results.json | Run a saved visitor or account report and return its results as JSON. | read | read | Current | |
Read-only. Works with saved visitor or account reports; Paths, Funnels, and Data Explorer reports are not available through the API. Acts onreport Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/report/{reportId}/results.csv | Run a saved visitor or account report and return its results as CSV. | read | read | Current | |
Read-only. An older report may need to be re-saved in the interface before it can be run through the API. Acts onreport Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Pendo's API does not push events to a subscriber. An app or AI agent learns about activity by running aggregation queries against the API, rather than receiving callbacks.
| Event | What it signals | Triggered by |
|---|
Pendo throttles how fast an app can call, returning a standard too-many-requests response when a caller goes over, and recommends batching metadata writes through the bulk methods rather than one record at a time.
Pendo does not publish exact request-rate thresholds for its public API; the documented behavior is that a caller going over the limit receives an HTTP 429 too-many-requests response. Pendo's guidance is to batch metadata writes through the bulk methods rather than sending one record per request, and to retry a 429 with exponential backoff. Rate-limit response headers are not documented.
Most data is read through the aggregation pipeline, where the caller controls volume by adding filter and limit operators to the JSON request rather than following page cursors. Aggregation also drives pulling visitors, since there is no simple paginated list-visitors endpoint. The feature, page, and guide list methods return the full set for an application, or for every application when expanded.
Pendo recommends keeping bulk metadata batches under 1,000 records per request. Reports return their full contents in one response, as JSON or CSV. Aggregation response size is bounded by the operators in the request rather than a fixed page size.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | unauthorized | No valid integration key was provided, or the key is wrong for the subscription. | Confirm a valid integration key is sent in the x-pendo-integration-key header, and rotate it if it may be compromised. |
| 403 | forbidden | The integration key lacks the level the request needs, for example a read-only key attempting a metadata write. | Use a read-write key for write methods, or restrict the agent to read methods. |
| 404 | not_found | The requested object does not exist or is not visible to this key, for example an unknown visitor, account, or report id. | Verify the id and confirm the object exists in this subscription. |
| 429 | too_many_requests | The caller exceeded Pendo's request rate. | Back off and retry with exponential backoff, and batch metadata writes through the bulk methods. |
Pendo serves a single version of its public API, addressed under a v1 path, and ships changes through dated release notes rather than minting new version strings.
Pendo serves a single public API version, addressed under the /api/v1 path and authenticated with an integration key. It centers on the aggregation query engine for reads, plus methods to set custom visitor and account metadata, list features, pages, and guides, read metadata schemas, and pull saved reports. Pendo ships changes through dated product release notes rather than minting new API version strings.
Pendo released an external, hosted Model Context Protocol server, making live Pendo product and customer data accessible to MCP-compatible AI clients like Claude, ChatGPT, Cursor, Gemini CLI, and Windsurf. It authenticates with OAuth and respects the connecting user's existing Pendo permissions. This is a new connection method for AI agents alongside the integration-key REST API, not a change to the v1 API itself.
There is one public API version; track the release notes for additive changes.
Pendo release notes ↗Bollard AI sits between a team's AI agents and Pendo. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.