generated: '2026-08-13'
method: searched
source: >-
  https://developers.google.com/google-ads/api/docs/concepts/call-structure,
  https://developers.google.com/google-ads/api/docs/best-practices/quotas,
  grpc/google-ads-google-ads-service.proto and
  discovery/google-ads-api-v25-discovery.json
provider: Google Ads
providerId: google-ads
description: >-
  Cross-cutting runtime semantics for the Google Ads API. This API is unusual enough
  that generic REST assumptions will break an agent: reads are a query language, writes
  are one `:mutate` operation per resource, and there is no idempotency key anywhere in
  the surface.

auth:
  style: oauth2 + developer token
  scheme: OAuth 2.0 authorization code, single scope https://www.googleapis.com/auth/adwords
  headers:
    - name: Authorization
      value: Bearer <access_token>
      required: true
    - name: developer-token
      required: true
      note: >-
        Issued per manager account in the API Center. Its access level (Test / Explorer /
        Basic / Standard) determines the daily operation quota, not the price.
    - name: login-customer-id
      required: conditional
      note: >-
        Required when operating on a client account through a manager account. Digits
        only, no hyphens.
    - name: linked-customer-id
      required: conditional
      note: Used by third-party app analytics providers acting on a linked account.
  see: authentication/google-ads-authentication.yml

reads:
  style: query-language
  language: GAQL (Google Ads Query Language)
  operations:
    - googleads_customers_googleAds_search
    - googleads_customers_googleAds_searchStream
  note: >-
    There is no per-resource GET collection endpoint. A read is a POST carrying a GAQL
    string: SELECT <fields> FROM <resource> [WHERE ...] [ORDER BY ...] [LIMIT n]
    [PARAMETERS ...]. Field legality is resource-specific and discoverable at runtime
    through googleAdsFields:search — the same operation Google's MCP server exposes as
    get_resource_metadata.
  field_discovery:
    operation: googleads_googleAdsFields_search
    returns: selectable / filterable / sortable flags plus compatible metrics and segments

writes:
  style: batched mutate
  pattern: POST /v25/customers/{customerId}/<resource>:mutate
  note: >-
    Nearly every resource exposes exactly one write operation taking an `operations`
    array of create / update / remove entries. There is no PUT, PATCH or DELETE on
    individual resources in the REST transport.
  update_mask:
    field: updateMask
    required_for_update: true
    note: >-
      An update operation must carry a field mask naming the fields being changed;
      omitted fields are left alone rather than cleared.
  cross_resource:
    operation: googleads_customers_googleAds_mutate
    note: >-
      GoogleAdsService.Mutate accepts operations across multiple resource types in one
      atomic request, which is how temp-id-linked object graphs (budget -> campaign ->
      ad group -> ad) are created in a single call.
  temp_ids:
    note: >-
      Negative resource IDs inside one mutate request act as forward references, letting
      a campaign reference a budget created in the same request.

idempotency:
  supported: false
  header: null
  note: >-
    The Google Ads API publishes no idempotency key, request-id-echo or replay-safe
    retry mechanism. A retried mutate that already succeeded will create duplicates.
    The safety mechanisms Google offers instead are validateOnly (dry run) and
    partialFailure (per-operation failure isolation), plus temp-ids to make a multi-object
    create atomic. Callers building retry logic must dedupe on their own side —
    typically by searching for the resource before recreating it.

safety_rails:
  - name: validateOnly
    type: boolean request field
    note: >-
      Runs the full validation path and returns errors without applying anything. The
      closest thing to a dry-run this API has.
  - name: partialFailure
    type: boolean request field
    note: >-
      When true, valid operations in a batch are applied and invalid ones are returned in
      a partial_failure_error naming each failed index. When false, one bad operation
      rolls back the whole request.
  - name: responseContentType
    type: enum
    note: >-
      RESOURCE_NAME_ONLY (default) or MUTABLE_RESOURCE — controls whether the mutated
      object comes back in the response, which materially changes payload size.

pagination:
  style: page token
  request_fields:
    - pageSize
    - pageToken
  response_fields:
    - nextPageToken
    - totalResultsCount
  default_page_size: 10000
  note: >-
    Applies to googleAds:search. googleAds:searchStream does not paginate — it streams
    the whole result set in chunks, which is why Google's own MCP server and most
    reporting code use searchStream. A paginated follow-up request carrying a valid page
    token is NOT counted again against the daily operation quota.

field_selection:
  style: explicit projection in the query
  note: >-
    GAQL SELECT is the sparse-fieldset mechanism; there is no `fields` query parameter and
    no expansion syntax. Adding `PARAMETERS omit_unselected_resource_names=true` drops the
    resource names of joined resources you did not ask for.

long_running:
  mechanism: google.longrunning.Operation
  operations:
    - googleads_customers_operations_get
    - googleads_customers_operations_list
    - googleads_customers_operations_wait
    - googleads_customers_operations_cancel
    - googleads_customers_operations_delete
  batch_jobs:
    - googleads_customers_batchJobs_mutate
    - googleads_customers_batchJobs_addOperations
    - googleads_customers_batchJobs_run
    - googleads_customers_batchJobs_listResults
  note: >-
    Bulk work above the 10,000-operations-per-request ceiling goes through BatchJobService,
    which is asynchronous: create the job, add operations, run it, then poll listResults.

tracing:
  request_id:
    field: requestId
    location: GoogleAdsFailure.request_id and the response metadata
    note: >-
      Every request gets an ID that Google support and the forum ask for when
      diagnosing. It is returned on both success and failure.

versioning:
  location: URL path segment (/v25/)
  see: lifecycle/google-ads-lifecycle.yml

errors:
  envelope: GoogleAdsFailure
  rfc9457: false
  see: errors/google-ads-problem-types.yml

rate_limit_signalling:
  headers: none
  note: >-
    No X-RateLimit-* or RateLimit-* response headers are published or observed. Throttling
    is signalled in-band by a RESOURCE_EXHAUSTED error whose QuotaErrorDetails carries
    rate_scope (ACCOUNT or DEVELOPER), rate_name, and a retry_delay duration. An agent
    must parse the error body to learn when to retry — the runtime signal is in the
    payload, not the headers.
  see: rate-limits/google-ads-rate-limits.yml

transports:
  message_size_limit: 64 MB
  available:
    - name: gRPC
      canonical: true
      note: >-
        The API is designed gRPC-first; the .proto files in grpc/ are the source of truth
        and the client libraries are generated from them.
    - name: REST/JSON
      canonical: false
      note: >-
        Described by the discovery document at
        https://googleads.googleapis.com/$discovery/rest?version=v25. Field names are
        lowerCamelCase in REST and snake_case in proto/GAQL, which is a frequent source of
        confusion when moving between the reference docs and the JSON transport.