> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shareofmodel.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Costs grouped by a dimension

> Cost per provider, code, module, service, model, tool, organization, workspace or analysis, most expensive first, with the credits consumed for organizations and workspaces. Period from `start` to `end` (inclusive dates, UTC, last 30 days by default, at most 731 days). `code` can be repeated and defaults to every cost type (LLM, tools, compute). Credits are null when a filter they cannot follow is set (analysis, provider, service, model, cost type). Staff only.



## OpenAPI

````yaml https://openapi.shareofmodel.ai/swagger.json get /v1/usage/costs/breakdown
openapi: 3.0.3
info:
  title: Share Of Model API
  version: v1
  description: >-
    ## Model Context Protocol (MCP)


    In addition to this REST API, Share of Model exposes a **Model Context
    Protocol** server that lets AI assistants (Claude Desktop, Claude Code, MCP
    Inspector, custom agents…) call our endpoints directly as tools. Any
    MCP-compatible client can interact with Share of Model without writing
    custom integration code — connect once with your usual login and start
    asking the assistant to query the data for you.


    ### Connecting from Claude Desktop


    Open **Settings → Connectors**, scroll to the bottom and click **Add custom
    connector**, then paste `https://mcp.shareofmodel.ai/mcp/`. A browser window
    opens for you to log in with your Share of Model account (same login as the
    web app), and the assistant gains access to the tools.


    ### Connecting from Claude Code


    ```bash

    claude mcp add --transport http share-of-model
    https://mcp.shareofmodel.ai/mcp/

    ```


    The first time you call a tool, Claude Code opens your browser to complete
    the login.


    ### Connecting from MCP Inspector


    ```bash

    npx @modelcontextprotocol/inspector

    ```


    In the Inspector UI, pick **Streamable HTTP** as transport, paste
    `https://mcp.shareofmodel.ai/mcp/`, and click **Connect**. The first
    connection prompts you to log in.


    ### Available tools


    Every read-only (`GET`) endpoint of this specification and of the Search API
    specification is exposed as an MCP tool, except account administration (API
    keys, platform integrations and accounts, user roles, favourites, SSO and
    SCIM).


    Write endpoints are exposed only when they are marked for agents: creating
    and pricing brand analyses, Search analyses and GEO audits, creating
    personas, and managing asset evaluations. Write tools act with the role of
    the signed-in user, so creating requires the Organization Editor or Owner
    role, or Workspace Editor in the target workspace. Before creating an
    analysis or a GEO audit, the assistant shows the full setup and its cost and
    waits for an explicit confirmation.


    ### Example prompts


    Once connected, try asking your assistant things like:


    - _"List the workspaces I have access to."_

    - _"Show me the latest searches in workspace X."_

    - _"Compare the share of model between brand A and brand B over the last 30
    days."_

    - _"Set up a brand analysis for brand A in France."_


    For more details on the protocol itself, see the [Model Context Protocol
    specification](https://modelcontextprotocol.io/).
servers:
  - description: Production API
    url: https://api.shareofmodel.ai/
  - description: Development API
    url: https://api.dev.shareofmodel.ai/
security: []
tags:
  - name: Auth
    description: Endpoints needed for API authentication.
  - name: Organizations
    description: Endpoints related to organizations, to list all available organizations.
  - name: Workspaces
    description: Endpoints related to workspaces, to list all available workspaces.
  - name: Analyses
    description: Endpoints related to analyses and analyses management.
  - name: Asset Evaluations
    description: Endpoints related to assets and asset evaluations.
  - name: Brand Catalog
    description: Endpoints related to general brand information.
  - name: Content Briefs
    description: Endpoints related to content briefs generation and optimisation.
  - name: Metrics
    description: >+
      Endpoints related to brand metrics.


      **LEXICON**



      **Brand Awareness**: What opinion the LLMs have concerning specific
      brands, related to certain categories.



      **Brand Perception**: The general sentiment of the LLMs towards a brand,

      based on the pros and cons they mention.

paths:
  /v1/usage/costs/breakdown:
    get:
      tags:
        - Usage costs
      summary: Costs grouped by a dimension
      description: >-
        Cost per provider, code, module, service, model, tool, organization,
        workspace or analysis, most expensive first, with the credits consumed
        for organizations and workspaces. Period from `start` to `end`
        (inclusive dates, UTC, last 30 days by default, at most 731 days).
        `code` can be repeated and defaults to every cost type (LLM, tools,
        compute). Credits are null when a filter they cannot follow is set
        (analysis, provider, service, model, cost type). Staff only.
      operationId: list_usage_cost_breakdown
      parameters:
        - in: query
          name: analysis_id
          schema:
            type: string
            maxLength: 255
            minLength: 1
        - in: query
          name: code
          schema:
            type: array
            items:
              enum:
                - llm_cost_usd
                - tool_cost_usd
                - compute_cost_usd
              type: string
              description: |-
                * `llm_cost_usd` - llm cost usd
                * `tool_cost_usd` - tool cost usd
                * `compute_cost_usd` - compute cost usd
              x-spec-enum-id: f427e86f937ee50d
        - in: query
          name: end
          schema:
            type: string
            format: date
        - in: query
          name: group_by
          schema:
            enum:
              - provider
              - code
              - module
              - service
              - model
              - tool
              - organization
              - workspace
              - analysis
            type: string
            x-spec-enum-id: a0730ca61a2d9ef5
            minLength: 1
          description: |-
            * `provider` - provider
            * `code` - code
            * `module` - module
            * `service` - service
            * `model` - model
            * `tool` - tool
            * `organization` - organization
            * `workspace` - workspace
            * `analysis` - analysis
          required: true
        - in: query
          name: limit
          schema:
            type: integer
            maximum: 500
            minimum: 1
            default: 50
        - in: query
          name: model
          schema:
            type: string
            maxLength: 255
            minLength: 1
        - in: query
          name: module
          schema:
            type: string
            maxLength: 50
            minLength: 1
        - in: query
          name: organization_id
          schema:
            type: string
            format: uuid
        - in: query
          name: provider
          schema:
            type: string
            maxLength: 100
            minLength: 1
        - in: query
          name: service
          schema:
            type: string
            maxLength: 50
            minLength: 1
        - in: query
          name: start
          schema:
            type: string
            format: date
        - in: query
          name: workspace_id
          schema:
            type: string
            format: uuid
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CostBreakdown'
          description: ''
        '400':
          description: Invalid filters.
        '403':
          description: Staff users only.
      security:
        - Bearer: []
components:
  schemas:
    CostBreakdown:
      type: object
      properties:
        group_by:
          type: string
        total_cost_usd:
          type: number
          format: double
        rows:
          type: array
          items:
            $ref: '#/components/schemas/CostBreakdownRow'
      required:
        - group_by
        - rows
        - total_cost_usd
    CostBreakdownRow:
      type: object
      properties:
        cost_usd:
          type: number
          format: double
        events:
          type: integer
        input_tokens:
          type: integer
        output_tokens:
          type: integer
        requests:
          type: integer
        key:
          type: string
          nullable: true
        label:
          type: string
        share:
          type: number
          format: double
        organization_id:
          type: string
          nullable: true
        organization_name:
          type: string
          nullable: true
        credits_consumed:
          type: integer
          nullable: true
      required:
        - cost_usd
        - credits_consumed
        - events
        - input_tokens
        - key
        - label
        - organization_id
        - organization_name
        - output_tokens
        - requests
        - share
  securitySchemes:
    Bearer:
      type: apiKey
      in: header
      name: Authorization

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.