Nexla

Nexla Usage API

The usage API from Nexla — 4 operation(s) for usage.

GitHub OpenAPI

Documentation

📖
Documentation
https://docs.nexla.com/dev-guides/nexla-api
📖
APIReference
https://docs.nexla.com/reference/nexla-api
📖
Authentication
https://raw.githubusercontent.com/api-evangelist/nexla/refs/heads/main/authentication/nexla-authentication.yml
📖
Documentation
https://docs.nexla.com/genai-rag/
📖
APIReference
https://docs.nexla.com/dev-guides/mcp-tools/tools-api

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/nexla/refs/heads/main/openapi/nexla-usage-api-openapi.yml

Other Resources

🔗
Conventions
https://raw.githubusercontent.com/api-evangelist/nexla/refs/heads/main/conventions/nexla-conventions.yml
🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/nexla/refs/heads/main/errors/nexla-problem-types.yml
🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/nexla/refs/heads/main/data-model/nexla-data-model.yml
🔗
Webhooks
https://raw.githubusercontent.com/api-evangelist/nexla/refs/heads/main/asyncapi/nexla-webhooks.yml
🔗
ToolCrosswalk
https://raw.githubusercontent.com/api-evangelist/nexla/refs/heads/main/mcp/nexla-tool-crosswalk.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/nexla-usage-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no email required.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

nexla-usage-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Nexla GenAI (RAG + MCPaaS) Usage API
  description: Combined Nexla GenAI RAG API Service and MCPaaS
  version: v0.2.3.3-combined
tags:
- name: usage
paths:
  /v1/mcpaas/admin/metrics/refresh:
    post:
      tags:
      - usage
      summary: Refresh Tool Metrics
      description: 'Run the tool_metrics periodic rollup for the given lookback window.


        Same shape as gateway.py''s trigger_vendor_sync: org-allowlist gated,

        meant to be hit by an external scheduler — no scheduler exists inside

        this codebase to invoke it automatically. lookback_hours is capped at

        168 (one week) — unbounded, this scans the full tool_receipts table for

        the window; org-allowlisted so the blast radius is internal, but the

        cap turns an accidental prod stall into a 422.'
      operationId: refresh_tool_metrics_v1_mcpaas_admin_metrics_refresh_post
      parameters:
      - name: lookback_hours
        in: query
        required: false
        schema:
          type: integer
          maximum: 168
          minimum: 1
          default: 6
          title: Lookback Hours
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-subject-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Subject-Id
      - name: x-actor-type
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Actor-Type
      - name: x-roles
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Roles
      - name: x-client-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Client-Id
      - name: X-Agent-Principal
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Agent-Principal
      - name: x-agent-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Agent-Id
      - name: x-agent-session-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Agent-Session-Id
      - name: x-upstream-app
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Upstream-App
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Refresh Tool Metrics V1 Mcpaas Admin Metrics Refresh Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/mcpaas/servers/{server_key}/activity:
    get:
      tags:
      - usage
      summary: Get Server Activity
      description: 'Who has hit this MCP server, and what happened on each call.


        ``server_key`` is the customer-facing identifier (the one baked into an

        MCP client''s actual connection URL) — resolved to a toolset exactly like

        real MCP traffic is (mirrors mcp/server.py). ``environment`` (default

        ``"prod"``) disambiguates which of that toolset''s environments to show,

        since one toolset can have more than one simultaneously-active export

        (e.g. dev + prod) — see 035/036''s migration comments.


        ``limit``/``offset`` paginate sessions (most recently active first);

        ``from``/``to`` filter each session''s calls by receipt ``created_at``.

        ``range`` (``1h``/``24h``/``7d``/``30d``) is the window for the separate

        ``metrics`` summary/top-tools blob, built from the tool_metrics rollup

        table rather than from the sessions/calls above. Each ``top_tools`` entry

        carries its own ``health`` status inline (no separate top-level list to

        re-join by tool_id). ``granularity`` (``15m``/``1h``/``1d``) still governs

        the internal bucket width used for ``peak_bucket``/``avg_calls_per_hour``

        — not every pair is valid (e.g. ``15m`` over ``30d`` would require

        thousands of internal points), see metrics_service.resolve_granularity;

        an invalid pair is a 422, not a 500. ``top_n`` caps ``top_tools``

        (remainder rolled into one "other" row).'
      operationId: get_server_activity_v1_mcpaas_servers__server_key__activity_get
      parameters:
      - name: server_key
        in: path
        required: true
        schema:
          type: string
          title: Server Key
      - name: from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: From
      - name: to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: To
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      - name: range
        in: query
        required: false
        schema:
          type: string
          pattern: ^(1h|24h|7d|30d)$
          default: 24h
          title: Range
      - name: granularity
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            pattern: ^(15m|1h|1d)$
          - type: 'null'
          title: Granularity
      - name: top_n
        in: query
        required: false
        schema:
          type: integer
          maximum: 50
          minimum: 1
          default: 10
          title: Top N
      - name: environment
        in: query
        required: false
        schema:
          type: string
          default: prod
          title: Environment
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-subject-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Subject-Id
      - name: x-actor-type
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Actor-Type
      - name: x-roles
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Roles
      - name: x-client-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Client-Id
      - name: X-Agent-Principal
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Agent-Principal
      - name: x-agent-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Agent-Id
      - name: x-agent-session-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Agent-Session-Id
      - name: x-upstream-app
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Upstream-App
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Server Activity V1 Mcpaas Servers  Server Key  Activity Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/mcpaas/clients/{client_id}/activity:
    get:
      tags:
      - usage
      summary: Get Client Activity
      description: 'What this client has done, across servers and sessions.


        ``client_id`` is an OAuth DCR identifier, not org-scoped on its own (DCR

        registration precedes org resolution — see mcp/auth.py), so the query

        always filters client_id together with org_id, never client_id alone.


        ``limit``/``offset`` paginate receipts, not sessions — a session''s

        ``calls`` here may reflect only part of its history if it spans a page.'
      operationId: get_client_activity_v1_mcpaas_clients__client_id__activity_get
      parameters:
      - name: client_id
        in: path
        required: true
        schema:
          type: string
          title: Client Id
      - name: from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: From
      - name: to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: To
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-subject-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Subject-Id
      - name: x-actor-type
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Actor-Type
      - name: x-roles
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Roles
      - name: x-client-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Client-Id
      - name: X-Agent-Principal
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Agent-Principal
      - name: x-agent-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Agent-Id
      - name: x-agent-session-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Agent-Session-Id
      - name: x-upstream-app
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Upstream-App
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Client Activity V1 Mcpaas Clients  Client Id  Activity Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/mcpaas/subjects/{subject_id}/activity:
    get:
      tags:
      - usage
      summary: Get Subject Activity
      description: 'What this subject has done, across servers and sessions.


        ``subject_id`` is populated for every auth method (unlike client_id,

        OAuth-only) but is caller-asserted, not verified, and just as not

        org-scoped on its own — same filtering/pagination caveats as

        get_client_activity above.'
      operationId: get_subject_activity_v1_mcpaas_subjects__subject_id__activity_get
      parameters:
      - name: subject_id
        in: path
        required: true
        schema:
          type: string
          title: Subject Id
      - name: from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: From
      - name: to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: To
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-subject-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Subject-Id
      - name: x-actor-type
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Actor-Type
      - name: x-roles
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Roles
      - name: x-client-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Client-Id
      - name: X-Agent-Principal
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Agent-Principal
      - name: x-agent-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Agent-Id
      - name: x-agent-session-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Agent-Session-Id
      - name: x-upstream-app
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Upstream-App
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Subject Activity V1 Mcpaas Subjects  Subject Id  Activity Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError