> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Suggest Google Ads campaigns

> <Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Turns a plain description of a business into two or three complete campaigns you can preview side by side and launch.

Each suggestion carries a `payload` you can send straight to [Create campaign](/api-reference/create-google-ads-campaign). The approaches differ by goal: Smart Search for traffic, Smart Search for leads, and Performance Max for leads. Nothing is saved.

You get at most three suggestions. `suggestion_count` accepts up to 5, but only three approaches exist, so 4 and 5 return the same three as 3 does.

The Performance Max suggestion cannot launch as-is: `payload.logo_url` and `payload.images` come back empty because this endpoint does not generate images, and Google requires both. Collect them before you send that payload.

Check `source` before presenting the copy as generated: `fallback` means the model did not run or returned nothing. `title` and `subtitle` are always English, even when the copy inside `payload` is in the app's language, so translate them yourself if you show them to someone.

This one call runs two language-model requests and debits the shared quota twice.

<Note>This endpoint runs a language model and draws on a shared quota of 20 requests per minute per app, which every Google Ads AI endpoint debits. Enterprise workspaces get a higher quota. A 429 means the quota is spent, not that this endpoint has its own limit.</Note>

<Note>This endpoint accepts a personal API key. Workspace API keys are not authorized for it and are rejected with a 403.</Note>



## OpenAPI

````yaml /developers/references/app-management/app-management-openapi.json post /api/apps/{app_id}/google-ads/campaigns/ai-suggestions
openapi: 3.1.0
info:
  title: Base44 App Management API
  version: 1.0.0
servers:
  - url: https://app.base44.com
security:
  - ApiKeyAuth: []
paths:
  /api/apps/{app_id}/google-ads/campaigns/ai-suggestions:
    post:
      summary: Suggest Google Ads campaigns
      description: >-
        <Info>This API is in beta. Endpoints, fields, and behavior may still
        change, so avoid depending on it in production.</Info>


        Turns a plain description of a business into two or three complete
        campaigns you can preview side by side and launch.


        Each suggestion carries a `payload` you can send straight to [Create
        campaign](/api-reference/create-google-ads-campaign). The approaches
        differ by goal: Smart Search for traffic, Smart Search for leads, and
        Performance Max for leads. Nothing is saved.


        You get at most three suggestions. `suggestion_count` accepts up to 5,
        but only three approaches exist, so 4 and 5 return the same three as 3
        does.


        The Performance Max suggestion cannot launch as-is: `payload.logo_url`
        and `payload.images` come back empty because this endpoint does not
        generate images, and Google requires both. Collect them before you send
        that payload.


        Check `source` before presenting the copy as generated: `fallback` means
        the model did not run or returned nothing. `title` and `subtitle` are
        always English, even when the copy inside `payload` is in the app's
        language, so translate them yourself if you show them to someone.


        This one call runs two language-model requests and debits the shared
        quota twice.


        <Note>This endpoint runs a language model and draws on a shared quota of
        20 requests per minute per app, which every Google Ads AI endpoint
        debits. Enterprise workspaces get a higher quota. A 429 means the quota
        is spent, not that this endpoint has its own limit.</Note>


        <Note>This endpoint accepts a personal API key. Workspace API keys are
        not authorized for it and are rejected with a 403.</Note>
      operationId: >-
        ai_campaign_suggestions_api_apps__app_id__google_ads_campaigns_ai_suggestions_post
      parameters:
        - name: app_id
          in: path
          required: true
          schema:
            type: string
            description: ID of the app you are planning a Google Ads campaign for.
            title: App Id
          description: ID of the app you are planning a Google Ads campaign for.
          example: 6820f3a4e7b91d003c45a1f2
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AICampaignBrief'
      responses:
        '200':
          description: Campaigns you can preview and launch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleAdsCampaignSuggestions'
        '401':
          description: Missing or invalid credentials.
        '403':
          description: >-
            You don't have access to this app, the app does not exist, or you
            used a workspace API key. A missing app and an app you cannot reach
            are deliberately the same answer.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: >-
            The shared AI quota for this app is spent. This endpoint debits it
            twice. Retry in a minute.
components:
  schemas:
    AICampaignBrief:
      properties:
        business_name:
          type: string
          title: Business Name
          description: Name of the business to build campaigns for.
          default: ''
          example: Nordwind Furniture
        business_description:
          type: string
          title: Business Description
          description: >-
            What the business sells, in a sentence or two. This is what the
            suggestions are built from.
          default: ''
          example: Handmade solid oak dining tables, built to order in San Francisco.
        landing_page_url:
          type: string
          title: Landing Page Url
          description: Page the campaigns would send people to.
          default: ''
          example: https://nordwind-furniture.com
        campaign_goal:
          type: string
          title: Campaign Goal
          description: 'What the campaigns are for: `traffic`, `leads` or `sales`.'
          default: traffic
          example: traffic
        daily_budget_micros:
          type: integer
          title: Daily Budget Micros
          description: >-
            Daily budget each suggestion is sized for, in micros (1,000,000
            micros = 1 unit of the account's currency).
          default: 30000000
          example: 30000000
        suggestion_count:
          type: integer
          maximum: 5
          minimum: 1
          title: Suggestion Count
          description: >-
            How many suggestions to return. Only three approaches exist, so 4
            and 5 return the same three as 3.
          default: 3
          example: 3
      type: object
      title: AICampaignBrief
    GoogleAdsCampaignSuggestions:
      properties:
        suggestions:
          items:
            $ref: '#/components/schemas/GoogleAdsCampaignSuggestion'
          type: array
          title: Suggestions
          description: >-
            The suggested campaigns, most general first. At most three, however
            many you asked for.
          example:
            - campaign_type: SMART
              estimate_source: heuristic
              estimated_daily_clicks: 24
              id: smart-traffic
              payload:
                business_name: Nordwind Furniture
                campaign_name: Nordwind Furniture - Traffic
                campaign_type: SMART
                daily_budget_micros: 30000000
                descriptions:
                  - Solid oak dining tables built to order.
                headlines:
                  - Handmade Oak Tables
                images: []
                keyword_themes:
                  - handmade oak furniture
                landing_page: https://nordwind-furniture.com
                logo_url: ''
                settings:
                  language_code: en
              subtitle: Best for raising overall visits to the site
              title: Smart Search - drive traffic
        language:
          anyOf:
            - type: string
            - type: 'null'
          title: Language
          description: >-
            Two-letter code for the language the generated copy came back in, or
            `null` when the model did not report one.
          example: en
        source:
          type: string
          title: Source
          description: >-
            `ai` when a language model wrote the copy in these suggestions,
            `fallback` when it did not run or returned nothing.
          example: ai
      type: object
      required:
        - suggestions
        - source
      title: GoogleAdsCampaignSuggestions
      description: Suggested campaigns for a business description.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    GoogleAdsCampaignSuggestion:
      properties:
        id:
          type: string
          title: Id
          description: >-
            Stable ID for the suggestion: `smart-traffic`, `smart-leads` or
            `pmax-leads`.
          example: smart-traffic
        title:
          type: string
          title: Title
          description: >-
            One-line name for the approach. Always English, even when the copy
            in `payload` is in another language.
          example: Smart Search - drive traffic
        subtitle:
          type: string
          title: Subtitle
          description: >-
            What this approach is best for. Always English, even when the copy
            in `payload` is in another language.
          example: Best for raising overall visits to the site
        campaign_type:
          type: string
          title: Campaign Type
          description: '`SMART` or `PERFORMANCE_MAX`.'
          example: SMART
        estimated_daily_clicks:
          type: integer
          title: Estimated Daily Clicks
          description: >-
            Rough daily clicks this approach could produce at the budget you
            sent. At least 1.
          example: 24
        estimate_source:
          type: string
          title: Estimate Source
          description: >-
            Where `estimated_daily_clicks` came from. `planner_anchored` means
            it is scaled from Google's own forecast for this account.
            `heuristic` means Google was not consulted, because the app has no
            connected account yet or the forecast was unavailable, and the
            number is a rough calculation from the budget alone.
          example: planner_anchored
        payload:
          $ref: '#/components/schemas/GoogleAdsCampaignSuggestionDraft'
          description: >-
            The campaign body to send to [Create
            campaign](/api-reference/create-google-ads-campaign) to launch this
            suggestion.
      type: object
      required:
        - id
        - title
        - subtitle
        - campaign_type
        - estimated_daily_clicks
        - estimate_source
        - payload
      title: GoogleAdsCampaignSuggestion
      description: One suggested campaign the caller can preview and launch.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    GoogleAdsCampaignSuggestionDraft:
      properties:
        campaign_name:
          type: string
          title: Campaign Name
          description: Suggested campaign name, trimmed to 120 characters.
          example: Nordwind Furniture - Traffic
        campaign_type:
          type: string
          title: Campaign Type
          description: '`SMART` or `PERFORMANCE_MAX`.'
          example: SMART
        business_name:
          type: string
          title: Business Name
          description: The business name you sent, echoed back.
          example: Nordwind Furniture
        landing_page:
          type: string
          title: Landing Page
          description: The `landing_page_url` you sent, echoed back.
          example: https://nordwind-furniture.com
        daily_budget_micros:
          type: integer
          title: Daily Budget Micros
          description: The `daily_budget_micros` you sent, echoed back.
          example: 30000000
        headlines:
          items:
            type: string
          type: array
          title: Headlines
          description: Generated headlines for the campaign's ads.
          example:
            - Handmade Oak Tables
            - Built To Order
        descriptions:
          items:
            type: string
          type: array
          title: Descriptions
          description: Generated description lines for the campaign's ads.
          example:
            - Solid oak dining tables built to order in San Francisco.
        keyword_themes:
          items:
            type: string
          type: array
          title: Keyword Themes
          description: Up to five generated keyword themes.
          example:
            - handmade oak furniture
            - custom dining tables
        settings:
          additionalProperties:
            type: string
          type: object
          title: Settings
          description: >-
            Campaign settings to send on unchanged. Carries `language_code`, the
            language this suggestion's copy was written in, whenever the model
            reported one; empty otherwise. Drop it and the campaign is created
            targeting English while its copy is not.
          example:
            language_code: de
        logo_url:
          type: string
          title: Logo Url
          description: >-
            Always empty. Performance Max campaigns need a logo to launch, so
            fill this in before you send the draft.
          example: ''
        images:
          items:
            type: string
          type: array
          title: Images
          description: >-
            Always empty. Performance Max campaigns need marketing images to
            launch, so fill these in before you send the draft.
          example: []
      type: object
      required:
        - campaign_name
        - campaign_type
        - business_name
        - landing_page
        - daily_budget_micros
        - headlines
        - descriptions
        - keyword_themes
        - settings
        - logo_url
        - images
      title: GoogleAdsCampaignSuggestionDraft
      description: >-
        A ready-to-send body for [Create
        campaign](/api-reference/create-google-ads-campaign).
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: api_key
      description: Personal API key.

````