Ads Lighthouse Google API

openapi: 3.2.0
info:
  title: Ads Lighthouse Google API
  version: 1.0.0
  description: Read account-scoped monitoring data and reports, and update project, team, alert and review workflows through the same services and limits as the app.
  contact:
    name: Ads Lighthouse
    url: https://adslighthouse.com/api
    email: info@adslighthouse.com
servers:
- url: https://adslighthouse.com/api/v1
security:
- bearerAuth: []
tags:
- name: Google
paths:
  /projects/{project_id}/google-connections:
    get:
      operationId: list_google_connections
      summary: Your Google Ads and Search Console connections in a project
      description: 'Lists the Google Ads and Search Console connections that the person the credential acts for made in this project, as in the app: other people''s connections are not visible to you. Connecting needs Google sign-in in the app (Settings > Connections); it cannot be done through the API. No tokens are returned.'
      tags:
      - Google
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 253
          description: 'The project: its id, its brand domain (for example nike.example) or its exact project or brand name. Unknown or ambiguous references return not_found; call list_projects then.'
        description: 'The project: its id, its brand domain (for example nike.example) or its exact project or brand name. Unknown or ambiguous references return not_found; call list_projects then.'
      security:
      - bearerAuth: []
      x-required-scope: read
      x-mcp-tool: list_google_connections
      responses:
        '200':
          description: Your Google Ads and Search Console connections in a project
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        type:
                          type: string
                          enum:
                          - google_ads
                          - search_console
                        status:
                          type: string
                          enum:
                          - active
                          - error
                          - disabled
                          description: Only active connections can run reports; reconnect others in the app.
                        created_at:
                          type: string
                      additionalProperties: false
                      required:
                      - id
                      - type
                      - status
                      - created_at
                  request_id:
                    type: string
                additionalProperties: false
                required:
                - data
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '429':
          $ref: '#/components/responses/Error429'
        '503':
          $ref: '#/components/responses/Error503'
  /projects/{project_id}/google-connections/{connection_id}/accounts:
    get:
      operationId: list_google_accounts
      summary: Google Ads customers or Search Console sites a connection can read
      description: Lists the Google Ads customer ids (for a google_ads connection) or Search Console properties (for a search_console connection) the connection can read, to pass to the report tools. Reads Google's data live with the connection of the person the credential acts for; nothing is saved and it uses no check allowance. Connecting or reconnecting needs Google sign-in in the app (Settings > Connections).
      tags:
      - Google
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 253
          description: 'The project: its id, its brand domain (for example nike.example) or its exact project or brand name. Unknown or ambiguous references return not_found; call list_projects then.'
        description: 'The project: its id, its brand domain (for example nike.example) or its exact project or brand name. Unknown or ambiguous references return not_found; call list_projects then.'
      - name: connection_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-f0-9]{32}$
          description: The connection id from list_google_connections.
        description: The connection id from list_google_connections.
      security:
      - bearerAuth: []
      x-required-scope: read
      x-mcp-tool: list_google_accounts
      responses:
        '200':
          description: Google Ads customers or Search Console sites a connection can read
          content:
            application/json:
              schema:
                type: object
                properties:
                  customers:
                    type: array
                    items:
                      type: object
                      properties:
                        customer_id:
                          type: string
                      additionalProperties: false
                      required:
                      - customer_id
                  sites:
                    type: array
                    items:
                      type: object
                      properties:
                        site_url:
                          type: string
                        permission_level:
                          type: string
                      additionalProperties: false
                      required:
                      - site_url
                      - permission_level
                  request_id:
                    type: string
                additionalProperties: false
                required:
                - customers
                - sites
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '429':
          $ref: '#/components/responses/Error429'
        '503':
          $ref: '#/components/responses/Error503'
  /projects/{project_id}/google-connections/{connection_id}/ads-report:
    get:
      operationId: run_google_ads_report
      summary: Keyword or search term performance from Google Ads
      description: Fetches a Google Ads keyword performance or search terms report for one customer and up to 31 days (from and to included). Use the keyword report to review the account's selected terms and the search-terms report to review queries recorded in that account. Rows carry clicks, impressions, cost in micros of the Google Ads account currency (divide by 1,000,000), conversions and conversion value. This is the connected customer's own advertising data; it reports that account's costs and conversions, and competitor spend cannot be inferred from it. Interpret conversions in light of the account's configured conversion actions and attribution. It is separate from saved ad observations. Page with next_page_token. Reads Google's data live with the connection of the person the credential acts for; nothing is saved and it uses no check allowance. Connecting or reconnecting needs Google sign-in in the app (Settings > Connections).
      tags:
      - Google
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 253
          description: 'The project: its id, its brand domain (for example nike.example) or its exact project or brand name. Unknown or ambiguous references return not_found; call list_projects then.'
        description: 'The project: its id, its brand domain (for example nike.example) or its exact project or brand name. Unknown or ambiguous references return not_found; call list_projects then.'
      - name: connection_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-f0-9]{32}$
          description: The connection id from list_google_connections.
        description: The connection id from list_google_connections.
      - name: customer_id
        in: query
        required: true
        schema:
          type: string
          pattern: ^(?:\d{10}|\d{3}-\d{3}-\d{4})$
          description: Customer id from list_google_accounts, such as 1234567890.
        description: Customer id from list_google_accounts, such as 1234567890.
      - name: login_customer_id
        in: query
        required: false
        schema:
          type: string
          pattern: ^(?:\d{10}|\d{3}-\d{3}-\d{4})$
          description: Manager account id when the customer is reached through a manager.
        description: Manager account id when the customer is reached through a manager.
      - name: from
        in: query
        required: true
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: First day, YYYY-MM-DD.
        description: First day, YYYY-MM-DD.
      - name: to
        in: query
        required: true
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: Last day, YYYY-MM-DD, at most 30 days after from.
        description: Last day, YYYY-MM-DD, at most 30 days after from.
      - name: report
        in: query
        required: false
        schema:
          type: string
          enum:
          - keywords
          - search-terms
          default: keywords
      - name: page_token
        in: query
        required: false
        schema:
          type: string
          minLength: 1
          maxLength: 8192
      security:
      - bearerAuth: []
      x-required-scope: read
      x-mcp-tool: run_google_ads_report
      responses:
        '200':
          description: Keyword or search term performance from Google Ads
          content:
            application/json:
              schema:
                type: object
                properties:
                  rows:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          anyOf:
                          - type: string
                          - type: 'null'
                        campaign_id:
                          anyOf:
                          - type: string
                          - type: 'null'
                        campaign_name:
                          anyOf:
                          - type: string
                          - type: 'null'
                        ad_group_id:
                          anyOf:
                          - type: string
                          - type: 'null'
                        ad_group_name:
                          anyOf:
                          - type: string
                          - type: 'null'
                        keyword:
                          anyOf:
                          - type: string
                          - type: 'null'
                        match_type:
                          anyOf:
                          - type: string
                          - type: 'null'
                        search_term:
                          anyOf:
                          - type: string
                          - type: 'null'
                        clicks:
                          anyOf:
                          - type: number
                          - type: 'null'
                        impressions:
                          anyOf:
                          - type: number
                          - type: 'null'
                        cost_micros:
                          anyOf:
                          - type: string
                          - type: 'null'
                        conversions:
                          anyOf:
                          - type: number
                          - type: 'null'
                        conversions_value:
                          anyOf:
                          - type: number
                          - type: 'null'
                      additionalProperties: false
                      required:
                      - date
                      - campaign_id
                      - campaign_name
                      - ad_group_id
                      - ad_group_name
                      - keyword
                      - match_type
                      - search_term
                      - clicks
                      - impressions
                      - cost_micros
                      - conversions
                      - conversions_value
                  next_page_token:
                    anyOf:
                    - type: string
                    - type: 'null'
                  fetched_at:
                    type: string
                  request_id:
                    type: string
                additionalProperties: false
                required:
                - rows
                - next_page_token
                - fetched_at
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '429':
          $ref: '#/components/responses/Error429'
        '503':
          $ref: '#/components/responses/Error503'
  /projects/{project_id}/google-connections/{connection_id}/search-console-report:
    get:
      operationId: run_search_console_report
      summary: Search Console clicks, impressions, CTR and position
      description: Fetches Search Console performance for one property and up to 31 days (from and to included), by date, query, page, country and device. Use clicks, impressions and CTR to assess organic Google Search visibility and find queries or pages to investigate. This is organic performance, separate from paid ads and the Google Ads report. ctr = clicks / impressions (0 to 1); position is Google's average position, so read it with clicks and impressions rather than as a fixed rank. Search Console returns top rows and may omit some data even when a request succeeds. Page with start_row (next_start_row). Reads Google's data live with the connection of the person the credential acts for; nothing is saved and it uses no check allowance. Connecting or reconnecting needs Google sign-in in the app (Settings > Connections).
      tags:
      - Google
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 253
          description: 'The project: its id, its brand domain (for example nike.example) or its exact project or brand name. Unknown or ambiguous references return not_found; call list_projects then.'
        description: 'The project: its id, its brand domain (for example nike.example) or its exact project or brand name. Unknown or ambiguous references return not_found; call list_projects then.'
      - name: connection_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-f0-9]{32}$
          description: The connection id from list_google_connections.
        description: The connection id from list_google_connections.
      - name: site_url
        in: query
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 2048
          description: Property from list_google_accounts, such as https://example.com/ or sc-domain:example.com.
        description: Property from list_google_accounts, such as https://example.com/ or sc-domain:example.com.
      - name: from
        in: query
        required: true
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: First day, YYYY-MM-DD.
        description: First day, YYYY-MM-DD.
      - name: to
        in: query
        required: true
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: Last day, YYYY-MM-DD, at most 30 days after from.
        description: Last day, YYYY-MM-DD, at most 30 days after from.
      - name: start_row
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          maximum: 1000000
          default: 0
      - name: row_limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 25000
          default: 1000
      security:
      - bearerAuth: []
      x-required-scope: read
      x-mcp-tool: run_search_console_report
      responses:
        '200':
          description: Search Console clicks, impressions, CTR and position
          content:
            application/json:
              schema:
                type: object
                properties:
                  rows:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                        query:
                          type: string
                        page:
                          type: string
                        country:
                          type: string
                        device:
                          type: string
                        clicks:
                          type: number
                        impressions:
                          type: number
                        ctr:
                          type: number
                        position:
                          type: number
                      additionalProperties: false
                      required:
                      - date
                      - query
                      - page
                      - country
                      - device
                      - clicks
                      - impressions
                      - ctr
                      - position
                  next_start_row:
                    anyOf:
                    - type: integer
                    - type: 'null'
                  fetched_at:
                    type: string
                  request_id:
                    type: string
                additionalProperties: false
                required:
                - rows
                - next_start_row
                - fetched_at
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '429':
          $ref: '#/components/responses/Error429'
        '503':
          $ref: '#/components/responses/Error503'
components:
  responses:
    Error401:
      description: Missing, invalid, expired or revoked credential.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error429:
      description: Rate limit reached. Retry after the Retry-After seconds.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error409:
      description: The idempotency key was already used for a different request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error503:
      description: The requested service or file is temporarily unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error403:
      description: The credential lacks the write scope, the plan does not include the API, or the allowance is used up.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error404:
      description: Unknown project, keyword or run in this account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error400:
      description: Invalid parameters, cursor or body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - invalid_request
              - idempotency_key_required
              - unauthorized
              - forbidden
              - insufficient_scope
              - plan_required
              - quota_exceeded
              - not_found
              - method_not_allowed
              - conflict
              - idempotency_key_reused
              - payload_too_large
              - unsupported_media_type
              - rate_limited
              - internal_error
              - unavailable
            message:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  message:
                    type: string
                required:
                - field
                - message
          required:
          - code
          - message
        request_id:
          type: string
      required:
      - error
      - request_id
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key from Settings > API and MCP (als_...), or an OAuth access token issued for this API.