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