Google Ads Customers.asset Groups API

openapi: 3.2.0
info:
  title: Google Ads Customers.asset Groups 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.assetGroups
paths:
  /v25/customers/{customersId}/assetGroups: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_assetGroups_mutate
      summary: Creates, updates or removes asset groups
      tags:
      - customers.assetGroups
      description: Creates, updates or removes asset groups. Operation statuses are returned.
      parameters:
      - name: customerId
        in: path
        required: true
        schema:
          type: string
          pattern: ^[^/]+$
        description: Required. The ID of the customer whose asset groups are being modified.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__MutateAssetGroupsRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__MutateAssetGroupsResponse'
      security:
      - oauth2:
        - https://www.googleapis.com/auth/adwords
components:
  schemas:
    GoogleAdsGoogleadsV25Services__MutateAssetGroupsResponse:
      description: Response message for an asset group 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__MutateAssetGroupResult'
    GoogleAdsGoogleadsV25Resources__AssetGroup:
      description: An asset group. AssetGroupAsset is used to link an asset to the asset group. AssetGroupSignal is used to associate a signal to an asset group.
      type: object
      properties:
        googleLocalServicesInfo:
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Resources__GoogleLocalServicesInfo'
          description: Local services info of the asset group.
        resourceName:
          description: 'Immutable. The resource name of the asset group. Asset group resource names have the form: `customers/{customer_id}/assetGroups/{asset_group_id}`'
          type: string
        assetCoverage:
          description: Output only. The asset coverage of this asset group.
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Resources__AssetCoverage'
        finalUrls:
          description: A list of final URLs after all cross domain redirects. In performance max, by default, the urls are eligible for expansion unless opted out.
          items:
            type: string
          type: array
        id:
          description: Output only. The ID of the asset group.
          type: string
          format: int64
        name:
          type: string
          description: Required. Name of the asset group. Required. It must have a minimum length of 1 and maximum length of 128. It must be unique under a campaign.
        path2:
          description: Second part of text that may appear appended to the url displayed in the ad. This field can only be set when path1 is set.
          type: string
        campaign:
          description: Immutable. The campaign with which this asset group is associated. The asset which is linked to the asset group.
          type: string
        status:
          description: The status of the asset group.
          type: string
          x-enumDescriptions:
          - The status has not been specified.
          - The received value is not known in this version.
          - The asset group is enabled.
          - The asset group is paused.
          - The asset group is removed.
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - ENABLED
          - PAUSED
          - REMOVED
        primaryStatusReasons:
          type: array
          description: Output only. Provides reasons into why an asset group is not serving or not serving optimally. It will be empty when the asset group is serving without issues.
          items:
            type: string
            x-enumDescriptions:
            - Not specified.
            - Used for return value only. Represents value unknown in this version.
            - The user-specified asset group status is paused. Contributes to AssetGroupPrimaryStatus.PAUSED
            - The user-specified asset group status is removed. Contributes to AssetGroupPrimaryStatus.REMOVED.
            - The user-specified campaign status is removed. Contributes to AssetGroupPrimaryStatus.NOT_ELIGIBLE.
            - The user-specified campaign status is paused. Contributes to AssetGroupPrimaryStatus.NOT_ELIGIBLE.
            - The user-specified time for this campaign to start is in the future. Contributes to AssetGroupPrimaryStatus.NOT_ELIGIBLE.
            - The user-specified time for this campaign to end has passed. Contributes to AssetGroupPrimaryStatus.NOT_ELIGIBLE.
            - The asset group is approved but only serves in limited capacity due to policies. Contributes to AssetGroupPrimaryStatus.LIMITED.
            - The asset group has been marked as disapproved. Contributes to AssetGroupPrimaryStatus.NOT_ELIGIBLE.
            - The asset group has not completed policy review. Contributes to AssetGroupPrimaryStatus.PENDING.
            enum:
            - UNSPECIFIED
            - UNKNOWN
            - ASSET_GROUP_PAUSED
            - ASSET_GROUP_REMOVED
            - CAMPAIGN_REMOVED
            - CAMPAIGN_PAUSED
            - CAMPAIGN_PENDING
            - CAMPAIGN_ENDED
            - ASSET_GROUP_LIMITED
            - ASSET_GROUP_DISAPPROVED
            - ASSET_GROUP_UNDER_REVIEW
        adStrength:
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - PENDING
          - NO_ADS
          - POOR
          - AVERAGE
          - GOOD
          - EXCELLENT
          description: Output only. Overall ad strength of this asset group.
          type: string
          x-enumDescriptions:
          - Not specified.
          - Used for return value only. Represents value unknown in this version.
          - The ad strength is currently pending.
          - No ads could be generated.
          - Poor strength.
          - Average strength.
          - Good strength.
          - Excellent strength.
        finalMobileUrls:
          description: A list of final mobile URLs after all cross domain redirects. In performance max, by default, the urls are eligible for expansion unless opted out.
          items:
            type: string
          type: array
        primaryStatus:
          x-enumDescriptions:
          - Not specified.
          - Used for return value only. Represents value unknown in this version.
          - The asset group is eligible to serve.
          - The asset group is paused.
          - The asset group is removed.
          - The asset group is not eligible to serve.
          - The asset group has limited servability.
          - The asset group is pending approval and may serve in the future.
          type: string
          description: Output only. The primary status of the asset group. Provides insights into why an asset group is not serving or not serving optimally.
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - ELIGIBLE
          - PAUSED
          - REMOVED
          - NOT_ELIGIBLE
          - LIMITED
          - PENDING
        path1:
          type: string
          description: First part of text that may appear appended to the url displayed in the ad.
    GoogleAdsGoogleadsV25Resources__AssetCoverage:
      type: object
      properties:
        adStrengthActionItems:
          description: Output only. A list of action items to improve the ad strength of an asset group.
          items:
            $ref: '#/components/schemas/GoogleAdsGoogleadsV25Resources__AdStrengthActionItem'
          type: array
      description: Information about the asset coverage of an asset group.
    GoogleAdsGoogleadsV25Resources__AdStrengthActionItem:
      type: object
      properties:
        actionItemType:
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - ADD_ASSET
          description: Output only. The action item type.
          type: string
          x-enumDescriptions:
          - Not specified.
          - Used for return value only. Represents value unknown in this version.
          - This action item suggests adding an asset to the asset group.
        addAssetDetails:
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Resources_AdStrengthActionItem_AddAssetDetails'
          description: Output only. The action item details for action item type ADD_ASSET.
      description: An action item to improve the ad strength of an asset group.
    GoogleAdsGoogleadsV25Resources__GoogleLocalServicesInfo:
      type: object
      properties:
        categoryId:
          type: string
          description: Immutable. The local services category associated with this asset group. That is, XCAT format - xcat:service_area_business_plumber. See https://developers.google.com/google-ads/api/data/codes-formats#local-services-category-ids This field cannot be modified after the AssetGroup has been created.
        callouts:
          description: Callouts selected by the advertiser to show.
          items:
            $ref: '#/components/schemas/GoogleAdsGoogleadsV25Resources__LocalServicesCallout'
          type: array
      description: Local services info for the asset group.
    GoogleAdsGoogleadsV25Services__MutateAssetGroupsRequest:
      description: Request message for AssetGroupService.MutateAssetGroups.
      type: object
      properties:
        validateOnly:
          type: boolean
          description: If true, the request is validated but not executed. Only errors are returned, not results.
        operations:
          description: Required. The list of operations to perform on individual asset groups.
          items:
            $ref: '#/components/schemas/GoogleAdsGoogleadsV25Services__AssetGroupOperation'
          type: array
    GoogleAdsGoogleadsV25Services__AssetGroupOperation:
      type: object
      properties:
        remove:
          type: string
          description: 'Remove operation: A resource name for the removed asset group is expected, in this format: `customers/{customer_id}/assetGroups/{asset_group_id}`'
        updateMask:
          description: FieldMask that determines which resource fields are modified in an update.
          type: string
          format: google-fieldmask
        create:
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Resources__AssetGroup'
          description: 'Create operation: No resource name is expected for the new asset group'
        update:
          description: 'Update operation: The asset group is expected to have a valid resource name.'
          $ref: '#/components/schemas/GoogleAdsGoogleadsV25Resources__AssetGroup'
      description: A single operation (create, remove) on an asset group.
    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.
    GoogleAdsGoogleadsV25Services__MutateAssetGroupResult:
      type: object
      properties:
        resourceName:
          description: Returned for successful operations.
          type: string
      description: The result for the asset group mutate.
    GoogleAdsGoogleadsV25Resources_AdStrengthActionItem_AddAssetDetails:
      description: The details of the asset to add.
      type: object
      properties:
        assetCount:
          format: int32
          type: integer
          description: Output only. The number of assets to add.
        videoAspectRatioRequirement:
          x-enumDescriptions:
          - Not specified.
          - The received value is not known in this version.
          - The video requires a horizontal aspect ratio.
          - The video requires a square aspect ratio.
          - The video requires a vertical aspect ratio.
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - HORIZONTAL
          - SQUARE
          - VERTICAL
          description: Output only. For video field types, the required aspect ratio of the video. When unset and asset_field_type is YOUTUBE_VIDEO, the system recommends the advertiser upload any YouTube video, regardless of aspect ratio.
          type: string
        assetFieldType:
          enum:
          - UNSPECIFIED
          - UNKNOWN
          - HEADLINE
          - DESCRIPTION
          - MANDATORY_AD_TEXT
          - MARKETING_IMAGE
          - MEDIA_BUNDLE
          - YOUTUBE_VIDEO
          - BOOK_ON_GOOGLE
          - LEAD_FORM
          - PROMOTION
          - CALLOUT
          - STRUCTURED_SNIPPET
          - SITELINK
          - MOBILE_APP
          - HOTEL_CALLOUT
          - CALL
          - PRICE
          - LONG_HEADLINE
          - BUSINESS_NAME
          - SQUARE_MARKETING_IMAGE
          - PORTRAIT_MARKETING_IMAGE
          - LOGO
          - LANDSCAPE_LOGO
          - VIDEO
          - CALL_TO_ACTION_SELECTION
          - AD_IMAGE
          - BUSINESS_LOGO
          - HOTEL_PROPERTY
          - DEMAND_GEN_CAROUSEL_CARD
          - BUSINESS_MESSAGE
          - TALL_PORTRAIT_MARKETING_IMAGE
          - RELATED_YOUTUBE_VIDEOS
          - LANDING_PAGE_PREVIEW
          - LONG_DESCRIPTION
          - CALL_TO_ACTION
          - CLASSIC_DISPLAY_IMAGE
          description: Output only. The asset field type of the asset(s) to add.
          type: string
          x-enumDescriptions:
          - Not specified.
          - Used for return value only. Represents value unknown in this version.
          - The asset is linked for use as a headline.
          - The asset is linked for use as a description.
          - The asset is linked for use as mandatory ad text.
          - The asset is linked for use as a marketing image.
          - The asset is linked for use as a media bundle.
          - The asset is linked for use as a YouTube video.
          - The asset is linked to indicate that a hotels campaign is "Book on Google" enabled.
          - The asset is linked for use as a Lead Form extension.
          - The asset is linked for use as a Promotion extension.
          - The asset is linked for use as a Callout extension.
          - The asset is linked for use as a Structured Snippet extension.
          - The asset is linked for use as a Sitelink.
          - The asset is linked for use as a Mobile App extension.
          - The asset is linked for use as a Hotel Callout extension.
          - The asset is linked for use as a Call extension.
          - The asset is linked for use as a Price extension.
          - The asset is linked for use as a long headline.
          - The asset is linked for use as a business name.
          - The asset is linked for use as a square marketing image.
          - The asset is linked for use as a portrait marketing image.
          - The asset is linked for use as a logo.
          - The asset is linked for use as a landscape logo.
          - The asset is linked for use as a non YouTube logo.
          - The asset is linked for use to select a call-to-action.
          - The asset is linked for use to select an ad image.
          - The asset is linked for use as a business logo.
          - The asset is linked for use as a hotel property in a Performance Max for travel goals campaign.
          - The asset is linked for use as a Demand Gen carousel card.
          - The asset is linked for use as a Business Message.
          - The asset is linked for use as a tall portrait marketing image.
          - The asset is linked for use as related YouTube videos.
          - The asset is linked for use as a landing page preview image.
          - The asset is linked for use as a long description.
          - The asset is linked for use as a call-to-action.
          - The asset is linked for use as a classic display image.
    GoogleAdsGoogleadsV25Resources__LocalServicesCallout:
      description: Local services callout of the asset group.
      type: object
      properties:
        calloutId:
          type: string
          description: Required. The unique ID of the callout.
  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