A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Google Forms API is how an app or AI agent works with a Google form: creating a form, adding and editing its questions in a single batch, reading the answers people submit, and setting whether the form is published. Access is granted through an OAuth 2.0 token and the scopes it carries, and an agent is limited to the forms that the authorizing user or service account can reach. It can also push a notification when a form changes or a response arrives, so an integration learns about activity without polling.
How an app or AI agent connects to Google Forms determines what it can reach. The route for making calls is governed by an OAuth token and the scopes it carries, and a separate route can push event notifications to a Cloud Pub/Sub topic the agent watches.
The REST API answers at https://forms.googleapis.com under the v1 path. It covers creating and editing forms, reading responses, and managing watches, and authenticates with an OAuth 2.0 access token.
A watch pushes a notification to a Cloud Pub/Sub topic when a form's schema changes or a response is submitted, so an agent learns about activity without polling. The notification carries identifiers, and the form or response is then read through the REST API.
An app or AI agent obtains an OAuth 2.0 access token after a user grants the requested Forms scopes, and acts within what that user can reach. The narrow scopes, such as forms.body.readonly and forms.responses.readonly, allow least-privilege access.
A service account is a non-human Google identity that authenticates on its own, suited to server-side automation. It reaches a form when that form has been shared with the service account, or through domain-wide delegation in Google Workspace.
The Google Forms API is split into three areas an agent can act on: the form itself, the responses people submit, and watches that push change notifications. Each area has its own methods and its own scopes, and writes here change a real form or the events it pushes.
Create a form, read a form's structure and settings, change it with a batch of updates that add, move, edit, or delete items, and set whether it is published.
List the responses people have submitted to a form, and read a single response by its id.
Create a watch that pushes change or response notifications to a Cloud Pub/Sub topic, list the watches a project owns on a form, renew one for another seven days, and delete one.
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 | |
|---|---|---|---|---|---|---|
FormsCreate a form, read a form's structure and settings, change it with a batch of updates that add, move, edit, or delete items, and set whether it is published.4 | ||||||
| POST | /v1/forms | Create a new form using the title given in the provided form in the request. | write | forms.body | Current | |
Requires one of https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/drive.file, or https://www.googleapis.com/auth/forms.body. From 30 June 2026 a form created through the API starts unpublished and needs setPublishSettings before it can take responses. Acts onform Permission (capability) forms.bodyVersionAvailable since the API’s base version Webhook eventNone Rate limitWrite request, 375 per minute per project and 150 per minute per user. SourceOfficial documentation ↗ | ||||||
| GET | /v1/forms/{formId} | Get a form, including its items, settings, and metadata. | read | forms.body.readonly | Current | |
Requires one of https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/drive.file, https://www.googleapis.com/auth/drive.readonly, https://www.googleapis.com/auth/forms.body, or https://www.googleapis.com/auth/forms.body.readonly. The readonly scope reads the structure without granting any write. Acts onform Permission (capability) forms.body.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitRead request, 975 per minute per project and 390 per minute per user. SourceOfficial documentation ↗ | ||||||
| POST | /v1/forms/{formId}:batchUpdate | Change the form with a batch of updates that create, move, edit, or delete items, and update form info or settings. | write | forms.body | Current | |
Requires one of https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/drive.file, or https://www.googleapis.com/auth/forms.body. Each request carries a list of write operations, such as createItem, moveItem, updateItem, deleteItem, updateFormInfo, and updateSettings, applied in order. Acts onform Permission (capability) forms.bodyVersionAvailable since the API’s base version Webhook eventNone Rate limitWrite request, 375 per minute per project and 150 per minute per user. SourceOfficial documentation ↗ | ||||||
| POST | /v1/forms/{formId}:setPublishSettings | Update the publish settings of a form, controlling whether it is published and accepting responses. | write | forms.body | Current | |
Requires one of https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/drive.file, or https://www.googleapis.com/auth/forms.body. Legacy forms without a publishSettings field are not supported. Acts onform Permission (capability) forms.bodyVersionAvailable since the API’s base version Webhook eventNone Rate limitWrite request, 375 per minute per project and 150 per minute per user. SourceOfficial documentation ↗ | ||||||
ResponsesList the responses people have submitted to a form, and read a single response by its id.2 | ||||||
| GET | /v1/forms/{formId}/responses | List a form's responses, with optional filtering and page-based paging. | read | forms.responses.readonly | Current | |
Requires one of https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/drive.file, or https://www.googleapis.com/auth/forms.responses.readonly. Returns the answers people submitted, which can include personal data. Acts onresponse Permission (capability) forms.responses.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitExpensive read request, 450 per minute per project and 180 per minute per user. SourceOfficial documentation ↗ | ||||||
| GET | /v1/forms/{formId}/responses/{responseId} | Get one response from the form by its response id. | read | forms.responses.readonly | Current | |
Requires one of https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/drive.file, or https://www.googleapis.com/auth/forms.responses.readonly. Returns one person's submitted answers, which can include personal data. Acts onresponse Permission (capability) forms.responses.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitRead request, 975 per minute per project and 390 per minute per user. SourceOfficial documentation ↗ | ||||||
WatchesCreate a watch that pushes change or response notifications to a Cloud Pub/Sub topic, list the watches a project owns on a form, renew one for another seven days, and delete one.4 | ||||||
| POST | /v1/forms/{formId}/watches | Create a watch that pushes notifications to a Cloud Pub/Sub topic when the form schema changes or a response is submitted. | write | forms.body.readonly | Current | |
Requires one of https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/drive.file, https://www.googleapis.com/auth/drive.readonly, https://www.googleapis.com/auth/forms.body, https://www.googleapis.com/auth/forms.body.readonly, or https://www.googleapis.com/auth/forms.responses.readonly. The watch eventType is SCHEMA or RESPONSES, and the calling project must be able to publish to the named Pub/Sub topic. Acts onwatch Permission (capability) forms.body.readonlyVersionAvailable since the API’s base version Webhook event schemaRate limitWrite request, 375 per minute per project and 150 per minute per user. SourceOfficial documentation ↗ | ||||||
| GET | /v1/forms/{formId}/watches | Return the list of watches owned by the calling project on a form. | read | forms.body.readonly | Current | |
Requires one of https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/drive.file, https://www.googleapis.com/auth/drive.readonly, https://www.googleapis.com/auth/forms.body, https://www.googleapis.com/auth/forms.body.readonly, or https://www.googleapis.com/auth/forms.responses.readonly. Acts onwatch Permission (capability) forms.body.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitRead request, 975 per minute per project and 390 per minute per user. SourceOfficial documentation ↗ | ||||||
| POST | /v1/forms/{formId}/watches/{watchId}:renew | Renew an existing watch for seven more days before it expires. | write | forms.body.readonly | Current | |
Requires one of https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/drive.file, https://www.googleapis.com/auth/drive.readonly, https://www.googleapis.com/auth/forms.body, https://www.googleapis.com/auth/forms.body.readonly, or https://www.googleapis.com/auth/forms.responses.readonly. A watch expires seven days after creation unless renewed. Acts onwatch Permission (capability) forms.body.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitWrite request, 375 per minute per project and 150 per minute per user. SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/forms/{formId}/watches/{watchId} | Delete a watch so it stops pushing notifications. | write | forms.body.readonly | Current | |
Requires one of https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/drive.file, https://www.googleapis.com/auth/drive.readonly, https://www.googleapis.com/auth/forms.body, https://www.googleapis.com/auth/forms.body.readonly, or https://www.googleapis.com/auth/forms.responses.readonly. Acts onwatch Permission (capability) forms.body.readonlyVersionAvailable since the API’s base version Webhook eventNone Rate limitWrite request, 375 per minute per project and 150 per minute per user. SourceOfficial documentation ↗ | ||||||
Google Forms can notify an app or AI agent when a form's content changes or a new response arrives, instead of the app repeatedly asking. It delivers each notification to a Cloud Pub/Sub topic that a watch has been registered against, and the notification carries identifiers rather than the form or response data itself.
| Event | What it signals | Triggered by |
|---|---|---|
SCHEMA | Fires when a form's content or settings are edited, such as items being added, changed, or removed. | /v1/forms/{formId}/watches |
RESPONSES | Fires when a form response is submitted, covering both new and updated responses. | /v1/forms/{formId}/watches |
Google Forms limits how fast an app or AI agent can call, through per-minute request quotas counted both per project and per user, with reads, response listing, and writes each holding their own ceiling.
Google Forms counts requests per minute against two ceilings at once, a per-project ceiling and a per-user-per-project ceiling, and sorts methods into three buckets. Ordinary read requests, such as getting a form or a single response, allow 975 per minute per project and 390 per minute per user. Listing a form's responses is treated as an expensive read at 450 per minute per project and 180 per minute per user. Write requests, such as creating a form, batch updates, setting publish settings, and managing watches, allow 375 per minute per project and 150 per minute per user. Daily totals are unlimited, and exceeding a per-minute ceiling returns 429: Too many requests, which should be retried with exponential backoff.
Listing responses uses page-based paging through the pageSize and pageToken query parameters. A response carries a nextPageToken when more results exist, and that token is passed as pageToken on the next request until it is absent. When pageSize is not set, the list returns up to 5000 responses.
Requests and responses are JSON. A watch pushes a small notification carrying the form id, watch id, and event type rather than the form or response content, and each watch receives at most one notification every thirty seconds, so a single notification can represent several events.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | INVALID_ARGUMENT | The request is malformed, such as an invalid field, an unsupported batch operation, or a bad page token. | Correct the named field or parameter and resend the request. |
| 401 | UNAUTHENTICATED | The OAuth access token is missing, invalid, or expired. | Refresh or re-obtain the access token, then send it in the Authorization header. |
| 403 | PERMISSION_DENIED | The token is valid but lacks the scope for this call, or the user cannot reach the form, or a quota was exceeded. | Grant the required scope, confirm the user has access to the form, or wait for the quota to reset. |
| 404 | NOT_FOUND | The form, response, or watch does not exist, or the caller cannot see it. | Confirm the id is correct and the caller has access to the resource. |
| 429 | RESOURCE_EXHAUSTED | A per-minute request quota was exceeded, returned as 429: Too many requests. | Slow the request rate and retry with exponential backoff. |
| 500 | INTERNAL | An unexpected error occurred on Google's side. | Retry with exponential backoff, and report it if it persists. |
Google Forms exposes a single version of its API, v1. New capabilities ship as dated entries in the release notes rather than as a new version string.
The Google Forms API exposes a single version, v1, and gains capabilities as additive changes rather than new versions. On 8 April 2025 it gained publish settings, letting the API publish a form and use Drive permissions to control who can respond. From 30 June 2026, a form created through the API starts in an unpublished state and must be published explicitly with setPublishSettings, a change from the earlier published-by-default behavior.
The Google Forms API became generally available on 17 March 2022, opening programmatic creation and editing of forms and reading of responses to all developers.
There is one version to build against, and additive changes arrive without a version bump.
Google Forms API release notes ↗Bollard AI sits between a team's AI agents and Google Forms. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.