SearchApi Account & Analytics API

openapi: 3.2.0
info:
  title: SearchApi & Analytics Account 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.
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.
components:
  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.
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message. SearchApi does not use RFC 9457 problem+json.
  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.