SearchApi Account & Analytics API

openapi: 3.1.0
info:
  title: SearchApi Account & Analytics API
  version: v1
  description: >-
    The two account-management endpoints SearchApi documents alongside its SERP surface.
    `GET /api/v1/me` (the "Account API") returns the calling key's plan usage, remaining
    credits, current-hour search count and hourly rate limit. `GET /api/v1/search_analytics`
    (the "Search Analytics API") returns aggregated success rates, error rates and latency
    for the account's own searches, bucketed daily or hourly and optionally filtered to one
    engine.


    These are the only SearchApi endpoints that expose runtime quota and reliability
    signal, and they are the reason an agent can self-regulate against SearchApi's hourly
    cap: SearchApi returns NO `X-RateLimit-*` or `RateLimit-*` response headers, so
    `api_usage.hourly_rate_limit` and `api_usage.searches_this_hour` from this API are the
    only machine-readable view of remaining headroom.


    This description is GENERATED from the public documentation — SearchApi publishes no
    machine-readable OpenAPI. Only documented parameters and documented response fields are
    modeled. The `search_analytics` response is modeled to the depth the docs describe
    (`search_parameters`, `summary`, `performance_by_engine`, `buckets`) without inventing
    field names inside those objects that the documentation does not spell out.
  x-provenance:
    generated: '2026-08-13'
    method: generated
    source:
      - https://www.searchapi.io/docs/account-api
      - https://www.searchapi.io/docs/search-analytics-api
    note: >-
      Faithful reconstruction from the two public docs pages. The 200 example for
      /api/v1/me is copied verbatim from the docs. The 401 example is copied from a live
      unauthenticated probe of https://www.searchapi.io/api/v1/me on 2026-08-13.
  contact:
    name: SearchApi Support
    email: support@searchapi.io
    url: https://www.searchapi.io/docs/account-api
  termsOfService: https://www.searchapi.io/legal/terms
servers:
  - url: https://www.searchapi.io
    description: SearchApi production
security:
  - bearerAuth: []
  - apiKeyQuery: []
tags:
  - name: account
    description: Plan usage, credits and rate-limit headroom for the authenticated API key.
  - name: analytics
    description: Aggregated performance and error analytics for the account's own searches.
paths:
  /api/v1/me:
    get:
      operationId: getAccount
      summary: Get account usage, credits and hourly rate limit
      description: >-
        Returns the authenticated key's monthly allowance, month-to-date usage, remaining
        credits, searches made in the current hour, the hourly rate limit, and the current
        subscription period. Poll this to stay inside the documented cap of 20% of the
        plan's monthly credits per hour.
      tags:
        - account
      parameters:
        - name: api_key
          in: query
          required: false
          description: >-
            API key. Optional here only because the same key may instead be sent as
            `Authorization: Bearer <API_KEY>`; one of the two is required.
          schema:
            type: string
        - name: zero_retention
          in: query
          required: false
          description: >-
            Enterprise-only. Set to `true` to disable logging and storage of the request
            for compliance purposes.
          schema:
            type: boolean
      responses:
        '200':
          description: Account usage snapshot.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResponse'
              example:
                account:
                  current_month_usage: 4800
                  monthly_allowance: 10000
                  remaining_credits: 5200
                api_usage:
                  searches_this_hour: 250
                  hourly_rate_limit: 200000
                subscription:
                  period_start: '2024-12-04T00:34:59Z'
                  period_end: '2025-01-04T00:34:59Z'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Invalid API key.
  /api/v1/search_analytics:
    get:
      operationId: getSearchAnalytics
      summary: Get aggregated search analytics for the account
      description: >-
        Retrieves and explores the account's search analytics: aggregate speed, total
        searches, success rate and errors, optionally broken down per engine and bucketed
        by day or hour over a chosen time period.
      tags:
        - analytics
      parameters:
        - name: engine
          in: query
          required: false
          description: Filter to one engine by name, or `all` for every engine.
          schema:
            type: string
        - name: bucket
          in: query
          required: false
          description: Aggregation interval.
          schema:
            type: string
            enum:
              - daily
              - hourly
        - name: time_period
          in: query
          required: false
          description: Preset reporting window.
          schema:
            type: string
            enum:
              - last_day
              - last_week
              - last_month
              - last_6_months
              - last_year
        - name: time_period_min
          in: query
          required: false
          description: Start date or datetime of the window. Defaults to one month ago.
          schema:
            type: string
        - name: time_period_max
          in: query
          required: false
          description: End date or datetime of the window. Defaults to today.
          schema:
            type: string
        - name: api_key
          in: query
          required: false
          description: 'API key, if not supplied as an `Authorization: Bearer` header.'
          schema:
            type: string
        - name: zero_retention
          in: query
          required: false
          description: Enterprise-only. Disable logging and storage of the request.
          schema:
            type: boolean
      responses:
        '200':
          description: Analytics for the requested window.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchAnalyticsResponse'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key sent as `Authorization: Bearer <API_KEY>`.'
    apiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: API key sent as the `api_key` query-string parameter.
  schemas:
    AccountResponse:
      type: object
      properties:
        account:
          type: object
          properties:
            current_month_usage:
              type: integer
              description: Total searches performed this month.
            monthly_allowance:
              type: integer
              description: Maximum allowable searches per month on the current plan.
            remaining_credits:
              type: integer
              description: Search credits available for the remainder of the month.
        api_usage:
          type: object
          properties:
            searches_this_hour:
              type: integer
              description: Searches made in the current hour.
            hourly_rate_limit:
              type: integer
              description: >-
                Maximum searches allowed in the current hour. Documented as 20% of the
                plan's monthly credits.
        subscription:
          type: object
          properties:
            period_start:
              type: string
              format: date-time
              description: Current subscription period start.
            period_end:
              type: string
              format: date-time
              description: Current subscription period end.
    SearchAnalyticsResponse:
      type: object
      properties:
        search_parameters:
          type: object
          description: Echo of the request parameters used to build the report.
        summary:
          type: object
          description: >-
            Aggregate metrics across the window — average speed, total searches, success
            rate and errors.
        performance_by_engine:
          type: array
          description: >-
            Per-engine breakdown. Omitted when the request filtered to a single engine.
          items:
            type: object
        buckets:
          type: array
          description: >-
            Time-interval analytics, each carrying the interval start and end datetimes,
            speeds, search counts and error rates.
          items:
            type: object
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message. SearchApi does not use RFC 9457 problem+json.