Monocrawl Google Quick Search API

openapi: 3.2.0
info:
  title: Monocrawl Google Quick Search API
  version: 0.1.0
  description: One key, one envelope, one credit meter across social, search, commerce and web data.
  contact:
    name: Monocrawl support
    url: https://www.monocrawl.com/contact
  termsOfService: https://www.monocrawl.com/legal/terms-and-conditions
servers:
- url: https://www.monocrawl.com
security:
- ApiKeyHeader: []
tags:
- name: Google Quick Search
paths:
  /v1/google/search:
    get:
      operationId: google_search
      tags:
      - Google Quick Search
      summary: Web search
      description: 'Google organic results for a query: position, title, URL and description. Paged by page number. Costs 3 credits per successful live response.'
      parameters:
      - name: query
        in: query
        required: true
        schema:
          type: string
        example: best espresso machine
        description: Search term.
      - name: page
        in: query
        required: false
        schema:
          type: string
        description: Results page number, 1–11 (default 1). Omit page when using the returned cursor.
      - name: region
        in: query
        required: false
        schema:
          type: string
        example: US
        description: Two-letter region code to search from.
      - name: date_posted
        in: query
        required: false
        schema:
          type: string
          enum:
          - last-hour
          - last-day
          - last-week
          - last-month
          - last-year
          - past-hour
          - past-day
          - past-week
          - past-month
          - past-year
        description: 'Restrict by recency, e.g. past-week. Accepted values: last-hour, last-day, last-week, last-month, last-year, past-hour, past-day, past-week, past-month, past-year. Case, spaces, hyphens and underscores are interchangeable.'
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        example: ''
        description: Return the previous response cursor unchanged to continue with the same source. Keep query, region and date_posted unchanged; omit page. Each page costs the normal three credits. Availability of a backup depends on the requested search inputs.
      - name: dry_run
        in: query
        required: false
        schema:
          type: string
          enum:
          - '1'
          - '0'
          - 'true'
          - 'false'
        example: '1'
        description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.'
      - name: X-Max-Credits
        in: header
        required: false
        schema:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        example: 5
        description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs.
      security:
      - ApiKeyHeader: []
      - BearerKey: []
      responses:
        '200':
          description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.'
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Success'
                - type: object
                  properties:
                    data:
                      $schema: https://json-schema.org/draft/2020-12/schema
                      $id: https://www.monocrawl.com/schemas/google/search.json
                      title: google/search data fields
                      description: Optional data supplied by this operation. Null means unknown.
                      type: object
                      properties:
                        cursor:
                          description: Opaque next-page token; pass it back unchanged. Null does not prove complete history.
                          type:
                          - string
                          - 'null'
                        items:
                          description: Returned records. Source coverage and completeness vary.
                          type:
                          - array
                          items:
                            description: Optional record supplied by this operation. Null means unknown.
                            type: object
                            properties:
                              description:
                                description: Source description; null or absent means not supplied.
                                type:
                                - string
                                - 'null'
                              position:
                                description: Optional position supplied by this operation. Null means unknown.
                                type:
                                - number
                                - 'null'
                              title:
                                description: Source title when supplied.
                                type:
                                - string
                                - 'null'
                              url:
                                description: Original source URL when supplied.
                                type:
                                - string
                                - 'null'
                            additionalProperties: true
                            allOf:
                            - anyOf:
                              - required:
                                - description
                                properties:
                                  description:
                                    description: Source description; null or absent means not supplied.
                                    type:
                                    - string
                                    minLength: 1
                              - required:
                                - position
                                properties:
                                  position:
                                    description: Optional position supplied by this operation. Null means unknown.
                                    type:
                                    - number
                              - required:
                                - title
                                properties:
                                  title:
                                    description: Source title when supplied.
                                    type:
                                    - string
                                    minLength: 1
                              - required:
                                - url
                                properties:
                                  url:
                                    description: Original source URL when supplied.
                                    type:
                                    - string
                                    minLength: 1
                      additionalProperties: true
                      required:
                      - items
                      x-contract-version: '2026-09-22'
                      x-validation-scope: Required success payload structure; optional fields and source completeness remain separate.
                      examples:
                      - cursor: null
                        items:
                        - description: example
                          position: 0
                          title: example
                          url: https://example.com/example
        default:
          description: The error envelope — the same shape for every non-2xx status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-credits: 3
      x-production-available: true
      x-capacity:
        status: not_assessed
        message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee.
      x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes.
      x-live-proven: true
components:
  schemas:
    Error:
      type: object
      required:
      - success
      - error
      - credits_used
      - request_id
      properties:
        success:
          const: false
        error:
          type: object
          required:
          - type
          - message
          - status
          properties:
            type:
              type: string
              enum:
              - UNAUTHORIZED
              - KEY_REVOKED
              - KEY_LIMIT_EXCEEDED
              - RATE_LIMITED
              - INSUFFICIENT_CREDITS
              - RESOURCE_NOT_FOUND
              - INVALID_PARAMETERS
              - TARGET_ACCESS_DENIED
              - UPSTREAM_ERROR
              - UPSTREAM_TIMEOUT
              - FREE_CAPACITY_UNAVAILABLE
              - CAPACITY_UNAVAILABLE
              - ENDPOINT_NOT_FOUND
              - ENDPOINT_NOT_AVAILABLE
              - FAIR_USE_EXCEEDED
              - INTERNAL_ERROR
            message:
              type: string
            status:
              type: integer
            doc_url:
              type: string
              description: Deep link to the exact section of the errors guide for this type.
            details:
              type: object
        credits_used:
          type:
          - integer
          - 'null'
          description: Confirmed net charge; null when billing is pending reconciliation. Inspect error.details.billing_status and retain request_id.
        credits_remaining:
          type: integer
        request_id:
          type: string
    Success:
      type: object
      required:
      - success
      - platform
      - endpoint
      - data
      - credits_used
      - credits_remaining
      - request_id
      properties:
        _completeness:
          type: object
          description: Reported response completeness, not a guarantee of complete platform history. Missing source assertions remain unknown.
          properties:
            state:
              type: string
              enum:
              - complete
              - partial
              - unknown
            scope:
              type: string
            inspection_limited:
              type: boolean
        success:
          const: true
        platform:
          type: string
        endpoint:
          type: string
          description: The resolved path, e.g. `/v1/github/profile`.
        data:
          description: Amazon responses include marketplace.country and marketplace.domain (resolved request marketplace, UK by default). X profiles preserve location, bio_link and cover_url when supplied. TikTok profiles preserve commerce_user, seller, region, location and business_category when supplied; region identifies the account region rather than personal residence. TikTok comments use platform_default selection, which can change between fetches; keep the same video and options when following cursors. Amazon review variant is readable text. Facebook profiles preserve cover_url, following and created_at when supplied; likes_count and followers are distinct and follower totals may be rounded. Endpoint-specific normalized payload, not one universal post/profile schema. Many lists use items/count/cursor; a null cursor means no usable next cursor was supplied, not proof that all history was retrieved. Check has_more and warnings where present. Social full-profile bundles use posts_cursor and posts_pagination.next_params; retain all returned next parameters. YouTube channel bundles instead use recent_videos, cursor and recent_videos_pagination. Inspect complete/partial/legs where supplied for bounded or failed components. Optional model-derived fields are labelled, not source facts.
        credits_used:
          type: integer
        credits_remaining:
          type: integer
        request_id:
          type: string
        cached:
          type: boolean
        stale:
          type: boolean
          description: True only for an explicitly labelled, zero-credit reference snapshot served after a temporary upstream failure.
        age_seconds:
          type: integer
          minimum: 0
          description: Age of a stale snapshot since its original retrieval; not reset by outage recovery.
        fetched_at:
          type: string
          format: date-time
          description: Original retrieval time of a stale snapshot, in UTC.
        synthetic:
          type: boolean
          description: Present and true only on the explicitly requested /sandbox surface. Synthetic responses are representative and charged 0 credits; production /v1 never returns them.
        degraded:
          type: boolean
          description: Reserved for sandbox compatibility. Production /v1 reports upstream failure as an error and never serves a representative fallback.
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: Your API key (`mn_…`), from the console. The recommended style.
    BearerKey:
      type: http
      scheme: bearer
      description: The same key as a Bearer token, for clients that only expose an Authorization field. Keys are never accepted in the query string — URLs leak into logs and referrers.