openapi: 3.2.0
info:
  description: 'Manage existing proxy services using scoped Bearer keys. Default budget: 300 requests per minute per account, shared across keys and control replicas. On HTTP 429, wait for Retry-After. Protected responses use Cache-Control: no-store and X-Request-ID. Timestamps are ISO-8601; monetary amounts are cents. Use the dashboard for API key management. Creating and paying invoices requires billing:write or reseller:purchase.'
  title: TrueProxies Customer Analytics API
  version: 1.0.0
servers:
- url: https://api.trueproxies.com
tags:
- name: Analytics
paths:
  /v1/analytics:
    get:
      description: Analytics across the services owned by this account.
      operationId: get_v1_analytics
      parameters:
      - $ref: '#/components/parameters/CustomerId'
      - in: query
        name: range
        schema:
          default: 24h
          enum:
          - 24h
          - 7d
          - 30d
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analytics'
          description: ok
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '409':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Error'
      security:
      - customerAPIKey: []
      summary: Get account analytics
      x-api-key-scope: services:read
      x-required-scope: services:read
      tags:
      - Analytics
components:
  schemas:
    ErrorClass:
      properties:
        count:
          format: int64
          type: integer
        err_class:
          type: string
      required:
      - err_class
      - count
      type: object
    Error:
      properties:
        code:
          enum:
          - BAD_REQUEST
          - UNAUTHENTICATED
          - FORBIDDEN
          - NOT_FOUND
          - CONFLICT
          - RATE_LIMITED
          - SERVICE_UNAVAILABLE
          - OFFER_UNAVAILABLE
          - CITY_UNAVAILABLE
          - CAPACITY_UNAVAILABLE
          - INVOICE_NOT_PAYABLE
          - PROVIDER_ERROR
          - PIPE_UNAVAILABLE
          - TRIAL_NOT_ELIGIBLE
          - EMAIL_UNVERIFIED
          - INTERNAL
          type: string
        details:
          additionalProperties: true
          description: What a client needs to act on the error (ids, flags), never display text.
          type: object
        message:
          type: string
      required:
      - code
      - message
      type: object
    AnalyticsPoint:
      properties:
        avg_session_ms:
          description: Mean elapsed milliseconds of measured completed authenticated socket sessions; null when no samples exist.
          minimum: 0
          type:
          - number
          - 'null'
        avg_setup_ms:
          description: Mean gateway-to-destination setup milliseconds for measured successful initial TCP tunnels; null when no samples exist.
          minimum: 0
          type:
          - number
          - 'null'
        bytes_in:
          format: int64
          type: integer
        bytes_out:
          format: int64
          type: integer
        failures:
          format: int64
          type: integer
        requests:
          format: int64
          type: integer
        session_samples:
          description: Number of measured completed session samples in this bucket.
          minimum: 0
          type: integer
        setup_samples:
          description: Number of measured successful setup samples in this bucket.
          minimum: 0
          type: integer
        ts:
          format: date-time
          type: string
      required:
      - ts
      - requests
      - failures
      - bytes_in
      - bytes_out
      type: object
    Destination:
      properties:
        bytes:
          format: int64
          type: integer
        failures:
          format: int64
          type: integer
        host:
          type: string
        requests:
          format: int64
          type: integer
      required:
      - host
      - requests
      - failures
      - bytes
      type: object
    Analytics:
      properties:
        destinations:
          items:
            $ref: '#/components/schemas/Destination'
          type: array
        errors:
          items:
            $ref: '#/components/schemas/ErrorClass'
          type: array
        range:
          type: string
        series:
          items:
            $ref: '#/components/schemas/AnalyticsPoint'
          type: array
        success_rate:
          type: number
      required:
      - range
      - success_rate
      - series
      - destinations
      - errors
      type: object
  responses:
    Error:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: error
  parameters:
    CustomerId:
      description: Owned sub-customer UUID. Resellers only; reads require reseller:read and writes reseller:purchase in addition to the operation scope. X-Customer-Id header is an alternative. Not allowed for me, wallet, trial, API keys, or reseller-management routes.
      in: query
      name: customer_id
      schema:
        format: uuid
        type: string
  securitySchemes:
    customerAPIKey:
      bearerFormat: API key
      description: 'Send Authorization: Bearer tp_api_… . Create a named, scoped key in the customer dashboard. Keys expire after 30, 90 or 365 days and can be revoked immediately.'
      scheme: bearer
      type: http