Google Ads Customers.audiences API

openapi: 3.2.0
info:
  title: Google Ads Customers.audiences API
  description: Manage your Google Ads accounts, campaigns, and reports with this API.
  version: v25
  x-discovery-revision: '20260721'
  contact:
    name: Google
    url: https://developers.google.com/google-ads/api/
  termsOfService: https://developers.google.com/terms
servers:
- url: https://googleads.googleapis.com
  description: Google Ads API production server
security:
- oauth2:
  - https://www.googleapis.com/auth/adwords
tags:
- name: customers.audiences
paths:
  /v25/customers/{customersId}/audiences:mutate:
    parameters:
    - name: upload_protocol
      in: query
      required: false
      schema:
        type: string
      description: Upload protocol for media (e.g. "raw", "multipart").
    - name: quotaUser
      in: query
      required: false
      schema:
        type: string
      description: Available to use for quota purposes for server-side applications. Can be any arbitrary string assigned to a user, but should not exceed 40 characters.
    - name: fields
      in: query
      required: false
      schema:
        type: string
      description: Selector specifying which fields to include in a partial response.
    - name: $.xgafv
      in: query
      required: false
      schema:
        type: string
        enum:
        - '1'
        - '2'
        x-enumDescriptions:
        - v1 error format
        - v2 error format
      description: V1 error format.
    - name: callback
      in: query
      required: false
      schema:
        type: string
      description: JSONP
    - name: prettyPrint
      in: query
      required: false
      schema:
        type: boolean
        default: 'true'
      description: Returns response with indentations and line breaks.
    - name: access_token
      in: query
      required: false
      schema:
        type: string
      description: OAuth access token.
    - name: uploadType
      in: query
      required: false
      schema:
        type: string
      description: Legacy upload protocol for media (e.g. "media", "multipart").
    - name: key
      in: query
      required: false
      schema:
        type: string
      description: API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.
    - name: oauth_token
      in: query
      required: false
      schema:
        type: string
      description: OAuth 2.0 token for the current user.
    - name: alt
      in: query
      required: false
      schema:
        x-enumDescriptions:
        - Responses with Content-Type of application/json
        - Media download with context-dependent Content-Type
        - Responses with Content-Type of application/x-protobuf
        type: string
        default: json
        enum:
        - json
        - media
        - proto
      description: Data format for response.
    post:
      operationId: googleads_customers_audiences_mutate
      summary: Creates audiences
      tags:
      - customers.audiences
      description: 'Creates audiences. Operation statuses are returned. List of thrown errors: [AudienceError]()'
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          pattern: ^[^/]+$
          type: string
        description: Required. The ID of the customer whose audiences are being modified.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__MutateAudiencesRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__MutateAudiencesResponse'
      security:
      - oauth2:
        - https://www.googleapis.com/auth/adwords
components:
  schemas:
    GoogleAdsGoogleadsV25Common__LifeEventSegment:
      type: object
      properties:
        lifeEvent:
          description: The life event resource.
          type: string
      description: Live event segment.
    GoogleAdsGoogleadsV25Common__ExclusionSegment:
      description: An audience segment to be excluded from an audience.
      type: object
      properties:
        userList:
          description: User list segment to be excluded.
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Common__UserListSegment'
    GoogleAdsGoogleadsV25Services__MutateAudiencesResponse:
      description: Response message for an audience mutate.
      type: object
      properties:
        partialFailureError:
          description: Errors that pertain to operation failures in the partial failure mode. Returned only when partial_failure = true and all errors occur inside the operations. If any errors occur outside the operations (for example, auth errors), we return an RPC level error.
          $ref: '#/components/schemas/GoogleRpc__Status'
        results:
          type: array
          description: All results for the mutate.
          items:
            $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__MutateAudienceResult'
    GoogleAdsGoogleadsV25Services__MutateAudienceResult:
      description: The result for the audience mutate.
      type: object
      properties:
        resourceName:
          description: Returned for successful operations.
          type: string
        audience:
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Resources__Audience'
          description: The mutated Audience with only mutable fields after mutate. The field will only be returned when response_content_type is set to "MUTABLE_RESOURCE".
    GoogleRpc__Status:
      description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).'
      type: object
      properties:
        message:
          description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client.
          type: string
        code:
          type: integer
          description: The status code, which should be an enum value of google.rpc.Code.
          format: int32
        details:
          type: array
          description: A list of messages that carry the error details. There is a common set of message types for APIs to use.
          items:
            type: object
            additionalProperties:
              description: Properties of the object. Contains field @type with type URL.
    GoogleAdsGoogleadsV25Common__GenderDimension:
      description: Dimension specifying users by their gender.
      type: object
      properties:
        includeUndetermined:
          description: Include users whose gender is not determined.
          type: boolean
        genders:
          description: Included gender demographic segments.
          items:
            type: string
            x-enumDescriptions:
            - Not specified.
            - Used for return value only. Represents value unknown in this version.
            - Male.
            - Female.
            - Undetermined gender.
            enum:
            - UNSPECIFIED
            - UNKNOWN
            - MALE
            - FEMALE
            - UNDETERMINED
          type: array
    GoogleAdsGoogleadsV25Common__AudienceSegmentDimension:
      description: Dimension specifying users by their membership in other audience segments.
      type: object
      properties:
        segments:
          description: Included audience segments. Users are included if they belong to at least one segment.
          items:
            $ref: '#/components/schemas/GoogleAdsGoogleadsV25Common__AudienceSegment'
          type: array
    GoogleAdsGoogleadsV25Common__UserListSegment:
      description: User list segment.
      type: object
      properties:
        userList:
          type: string
          description: The user list resource.
    GoogleAdsGoogleadsV25Common__AudienceSegment:
      description: Positive audience segment.
      type: object
      properties:
        userInterest:
          description: Affinity or In-market segment.
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Common__UserInterestSegment'
        userList:
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Common__UserListSegment'
          description: User list segment.
        customAudience:
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Common__CustomAudienceSegment'
          description: Custom audience segment.
        lifeEvent:
          description: Live-event audience segment.
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Common__LifeEventSegment'
        detailedDemographic:
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Common__DetailedDemographicSegment'
          description: Detailed demographic segment.
    GoogleAdsGoogleadsV25Common__CustomAudienceSegment:
      type: object
      properties:
        customAudience:
          description: The custom audience resource.
          type: string
      description: Custom audience segment.
    GoogleAdsGoogleadsV25Common__AgeDimension:
      type: object
      properties:
        ageRanges:
          type: array
          description: Contiguous age range to be included in the dimension.
          items:
            $ref: '#/components/schemas/GoogleAdsGoogleadsV25Common__AgeSegment'
        includeUndetermined:
          type: boolean
          description: Include users whose age is not determined.
      description: Dimension specifying users by their age.
    GoogleAdsGoogleadsV25Resources__Audience:
      type: object
      properties:
        description:
          type: string
          description: Description of this audience.
        dimensions:
          type: array
          description: Positive dimensions specifying the audience composition.
          items:
            $ref: '#/components/schemas/GoogleAdsGoogleadsV25Common__AudienceDimension'
        exclusionDimension:
          description: Negative dimension specifying the audience composition.
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Common__AudienceExclusionDimension'
        name:
          description: Name of the audience. It should be unique across all audiences within the account. It must have a minimum length of 1 and maximum length of 255. Required when scope is not set or is set to CUSTOMER. Cannot be set or updated when scope is ASSET_GROUP.
          type: string
        scope:
          description: Defines the scope this audience can be used in. By default, the scope is CUSTOMER. Audiences can be created with a scope of ASSET_GROUP for exclusive use by a single asset_group. Scope may change from ASSET_GROUP to CUSTOMER but not from CUSTOMER to ASSET_GROUP.
          type: string
          x-enumDescriptions:
          - The scope has not been specified.
          - The received value is not known in this version.
          - The audience is scoped at the customer level.
          - The audience is scoped under a specific AssetGroup.
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - CUSTOMER
          - ASSET_GROUP
        assetGroup:
          description: Immutable. The asset group that this audience is scoped under. Must be set if and only if scope is ASSET_GROUP. Immutable after creation. If an audience with ASSET_GROUP scope is upgraded to CUSTOMER scope, this field will automatically be cleared.
          type: string
        id:
          description: Output only. ID of the audience.
          type: string
          format: int64
        status:
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - ENABLED
          - REMOVED
          description: Output only. Status of this audience. Indicates whether the audience is enabled or removed.
          type: string
          x-enumDescriptions:
          - Not specified.
          - Used for return value only. Represents value unknown in this version.
          - Enabled status - audience is enabled and can be targeted.
          - Removed status - audience is removed and cannot be used for targeting.
        resourceName:
          description: 'Immutable. The resource name of the audience. Audience names have the form: `customers/{customer_id}/audiences/{audience_id}`'
          type: string
      description: Audience is an effective targeting option that lets you intersect different segment attributes, such as detailed demographics and affinities, to create audiences that represent sections of your target segments.
    GoogleAdsGoogleadsV25Common__UserInterestSegment:
      type: object
      properties:
        userInterestCategory:
          description: The user interest resource.
          type: string
      description: User interest segment.
    GoogleAdsGoogleadsV25Common__DetailedDemographicSegment:
      description: Detailed demographic segment.
      type: object
      properties:
        detailedDemographic:
          description: The detailed demographic resource.
          type: string
    GoogleAdsGoogleadsV25Common__ParentalStatusDimension:
      type: object
      properties:
        parentalStatuses:
          description: Included parental status demographic segments.
          items:
            type: string
            x-enumDescriptions:
            - Not specified.
            - Used for return value only. Represents value unknown in this version.
            - Parent.
            - Not a parent.
            - Undetermined parental status.
            enum:
            - UNSPECIFIED
            - UNKNOWN
            - PARENT
            - NOT_A_PARENT
            - UNDETERMINED
          type: array
        includeUndetermined:
          description: Include users whose parental status is undetermined.
          type: boolean
      description: Dimension specifying users by their parental status.
    GoogleAdsGoogleadsV25Common__HouseholdIncomeDimension:
      type: object
      properties:
        incomeRanges:
          type: array
          description: Included household income demographic segments.
          items:
            x-enumDescriptions:
            - Not specified.
            - Used for return value only. Represents value unknown in this version.
            - 0%-50%.
            - 50% to 60%.
            - 60% to 70%.
            - 70% to 80%.
            - 80% to 90%.
            - Greater than 90%.
            - Undetermined income range.
            enum:
            - UNSPECIFIED
            - UNKNOWN
            - INCOME_RANGE_0_50
            - INCOME_RANGE_50_60
            - INCOME_RANGE_60_70
            - INCOME_RANGE_70_80
            - INCOME_RANGE_80_90
            - INCOME_RANGE_90_UP
            - INCOME_RANGE_UNDETERMINED
            type: string
        includeUndetermined:
          description: Include users whose household income is not determined.
          type: boolean
      description: Dimension specifying users by their household income.
    GoogleAdsGoogleadsV25Common__AudienceExclusionDimension:
      description: Negative dimension specifying users to exclude from the audience.
      type: object
      properties:
        exclusions:
          description: Audience segment to be excluded.
          items:
            $ref: '#/components/schemas/GoogleAdsGoogleadsV25Common__ExclusionSegment'
          type: array
    GoogleAdsGoogleadsV25Services__MutateAudiencesRequest:
      type: object
      properties:
        operations:
          description: Required. The list of operations to perform on individual audiences.
          items:
            $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__AudienceOperation'
          type: array
        validateOnly:
          type: boolean
          description: If true, the request is validated but not executed. Only errors are returned, not results.
        responseContentType:
          type: string
          description: The response content type setting. Determines whether the mutable resource or just the resource name should be returned post mutation.
          x-enumDescriptions:
          - Not specified. Will return the resource name only in the response.
          - The mutate response will be the resource name.
          - The mutate response will contain the resource name and the resource with mutable fields if possible. Otherwise, only the resource name will be returned.
          enum:
          - UNSPECIFIED
          - RESOURCE_NAME_ONLY
          - MUTABLE_RESOURCE
        partialFailure:
          description: If true, successful operations will be carried out and invalid operations will return errors. If false, all operations will be carried out in one transaction if and only if they are all valid. Default is false.
          type: boolean
      description: Request message for AudienceService.MutateAudiences.
    GoogleAdsGoogleadsV25Services__AudienceOperation:
      type: object
      properties:
        update:
          description: 'Update operation: The audience is expected to have a valid resource name.'
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Resources__Audience'
        updateMask:
          description: FieldMask that determines which resource fields are modified in an update.
          type: string
          format: google-fieldmask
        create:
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Resources__Audience'
          description: 'Create operation: No resource name is expected for the new audience'
      description: A single operation (create, update) on an audience.
    GoogleAdsGoogleadsV25Common__AudienceDimension:
      description: Positive dimension specifying user's audience.
      type: object
      properties:
        age:
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Common__AgeDimension'
          description: Dimension specifying users by their age.
        gender:
          description: Dimension specifying users by their gender.
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Common__GenderDimension'
        parentalStatus:
          description: Dimension specifying users by their parental status.
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Common__ParentalStatusDimension'
        householdIncome:
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Common__HouseholdIncomeDimension'
          description: Dimension specifying users by their household income.
        audienceSegments:
          description: Dimension specifying users by their membership in other audience segments.
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Common__AudienceSegmentDimension'
    GoogleAdsGoogleadsV25Common__AgeSegment:
      description: Contiguous age range.
      type: object
      properties:
        maxAge:
          format: int32
          type: integer
          description: Maximum age to include. A maximum age need not be specified. If specified, max_age must be greater than min_age, and allowed values are 24, 34, 44, 54, and 64.
        minAge:
          format: int32
          description: Minimum age to include. A minimum age must be specified and must be at least 18. Allowed values are 18, 25, 35, 45, 55, and 65.
          type: integer
  securitySchemes:
    oauth2:
      type: oauth2
      description: Google OAuth 2.0. Google Ads API additionally requires a developer token in the developer-token header.
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/auth
          tokenUrl: https://oauth2.googleapis.com/token
          scopes:
            https://www.googleapis.com/auth/adwords: See, edit, create, and delete your Google Ads accounts and data.
externalDocs:
  url: https://developers.google.com/google-ads/api/
x-source: https://googleads.googleapis.com/$discovery/rest?version=v25
x-generated-by: API Evangelist enrichment pipeline — mechanical conversion of the first-party Google API Discovery Document