> ## 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.

# Hierarchical Perception Tree View

> Provides a complete hierarchical tree structure showing clusters → attributes →
                   brands → sources, with mention counts at each level.

This endpoint returns a nested data structure perfect for visualization,
showing how perception flows from high-level themes (clusters) down through specific attributes, to which brands are associated with each attribute, and which AI sources mentioned them. The tree includes mention counts, making it easy to see volume and importance at each level. Ideal for comprehensive perception analysis and creating sunburst or tree visualizations.

**When to use:** User wants a complete hierarchical view of perception data, needs data structured for tree visualizations, wants to explore perception from themes down to specific brand mentions, or requires full detail with counts at every level.

**Common user queries:**
- "Show me the complete perception hierarchy"
- "Get the full cluster breakdown with brands"
- "I need hierarchical data for visualization"
- "Show clusters, attributes, and brands in a tree"
- "Get the nested structure of pros and cons"
- "What's the full breakdown from themes to mentions?"

**Returns:** Hierarchical tree object with nested children and mention counts.
Example: {"name": "pros", "children": [{"name": "Comfortable", "value": 450, "children": [{"name": "soft",
"value": 200, "children": [{"name": "Nike", "value": 120}]}]}]}

Required permission: `read:analysis`.



## OpenAPI

````yaml https://openapi.shareofmodel.ai/swagger.json get /v1/organizations/{organization_id}/workspaces/{workspace_id}/analyses/{analysis_id}/metrics/brand_perception/attributes_hierarchy_tree
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


    Only endpoints tagged `mcp` in this OpenAPI spec are exposed as MCP tools,
    and only read-only (`GET`) routes are exposed. Everything tagged `mcp` below
    is callable from any compliant MCP client.


    ### 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."_


    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/organizations/{organization_id}/workspaces/{workspace_id}/analyses/{analysis_id}/metrics/brand_perception/attributes_hierarchy_tree:
    get:
      tags:
        - Metrics
      summary: Hierarchical Perception Tree View
      description: >-
        Provides a complete hierarchical tree structure showing clusters →
        attributes →
                           brands → sources, with mention counts at each level.

        This endpoint returns a nested data structure perfect for visualization,

        showing how perception flows from high-level themes (clusters) down
        through specific attributes, to which brands are associated with each
        attribute, and which AI sources mentioned them. The tree includes
        mention counts, making it easy to see volume and importance at each
        level. Ideal for comprehensive perception analysis and creating sunburst
        or tree visualizations.


        **When to use:** User wants a complete hierarchical view of perception
        data, needs data structured for tree visualizations, wants to explore
        perception from themes down to specific brand mentions, or requires full
        detail with counts at every level.


        **Common user queries:**

        - "Show me the complete perception hierarchy"

        - "Get the full cluster breakdown with brands"

        - "I need hierarchical data for visualization"

        - "Show clusters, attributes, and brands in a tree"

        - "Get the nested structure of pros and cons"

        - "What's the full breakdown from themes to mentions?"


        **Returns:** Hierarchical tree object with nested children and mention
        counts.

        Example: {"name": "pros", "children": [{"name": "Comfortable", "value":
        450, "children": [{"name": "soft",

        "value": 200, "children": [{"name": "Nike", "value": 120}]}]}]}


        Required permission: `read:analysis`.
      operationId: attributes_hierarchy
      parameters:
        - in: path
          name: analysis_id
          schema:
            type: string
            format: uuid
          description: A UUID string identifying the analysis.
          required: true
        - in: query
          name: brand
          schema:
            type: string
          description: Filter by one specific brand.
        - in: query
          name: brand__in
          schema:
            type: string
          description: >-
            Filter by a list of brands. Values should be comma separated,
            without brackets or spaces
        - in: query
          name: cluster__in
          schema:
            type: string
          description: >-
            Filter by a list of clusters. Values should be comma separated,
            without brackets or spaces
        - in: query
          name: cluster_group
          schema:
            type: string
            enum:
              - all_cons
              - all_pros
          description: Filter by one specific cluster group.
          required: true
        - in: query
          name: collection_date
          schema:
            type: string
            format: date
          description: >-
            Filter by a collection date being equal to the specified date.
            YYYY-MM-DD format
        - in: query
          name: collection_date__gt
          schema:
            type: string
            format: date
          description: >-
            Filter by a collection date being greater than the specified date.
            YYYY-MM-DD format
        - in: query
          name: collection_date__gte
          schema:
            type: string
            format: date
          description: >-
            Filter by a collection date being greater than or equal the
            specified date. YYYY-MM-DD format
        - in: query
          name: collection_date__lt
          schema:
            type: string
            format: date
          description: >-
            Filter by a collection date being less than the specified date.
            YYYY-MM-DD format
        - in: query
          name: collection_date__lte
          schema:
            type: string
            format: date
          description: >-
            Filter by a collection date being less than or equal the specified
            date. YYYY-MM-DD format
        - in: query
          name: country
          schema:
            type: string
          description: Filter by one specific country.
        - in: query
          name: country__in
          schema:
            type: string
          description: >-
            Filter by a list of countries. Values should be comma separated,
            without brackets or spaces
        - in: query
          name: format
          schema:
            type: string
            enum:
              - csv
              - json
        - in: path
          name: organization_id
          schema:
            type: string
            format: uuid
          description: A UUID string identifying the organization.
          required: true
        - in: query
          name: persona
          schema:
            type: string
          description: Filter by one specific persona.
        - in: query
          name: persona__in
          schema:
            type: string
          description: >-
            Filter by a list of personas. Values should be comma separated,
            without brackets or spaces
        - in: query
          name: source
          schema:
            type: string
            enum:
              - claude-3-5-sonnet
              - claude-4-5-sonnet
              - claude-4-6-sonnet
              - claude-4-sonnet
              - deepseek-chat
              - deepseek-reasoner
              - deepseek-v3.2-maas
              - gemini-1.5-pro
              - gemini-2.0-flash
              - gemini-2.5-flash
              - gemini-2.5-flash-grounded
              - gemini-2.5-flash-lite
              - gemini-3-flash-preview
              - google-ai-mode
              - gpt-3.5-turbo
              - gpt-4-turbo
              - gpt-4o
              - gpt-4o-mini-search
              - gpt-5
              - gpt-5.2
              - gpt-5.4-mini
              - meta-llama-3.1-70B-instruct-turbo
              - meta-llama-3.2-70B-instruct-turbo
              - meta-llama-3.3-70B-instruct-turbo
              - meta-llama-4-maverick
              - mistral-7B-instruct
              - perplexity-sonar
              - rufus
          description: Filter by one specific source.
        - in: query
          name: source__in
          schema:
            type: string
            enum:
              - claude-3-5-sonnet
              - claude-4-5-sonnet
              - claude-4-6-sonnet
              - claude-4-sonnet
              - deepseek-chat
              - deepseek-reasoner
              - deepseek-v3.2-maas
              - gemini-1.5-pro
              - gemini-2.0-flash
              - gemini-2.5-flash
              - gemini-2.5-flash-grounded
              - gemini-2.5-flash-lite
              - gemini-3-flash-preview
              - google-ai-mode
              - gpt-3.5-turbo
              - gpt-4-turbo
              - gpt-4o
              - gpt-4o-mini-search
              - gpt-5
              - gpt-5.2
              - gpt-5.4-mini
              - meta-llama-3.1-70B-instruct-turbo
              - meta-llama-3.2-70B-instruct-turbo
              - meta-llama-3.3-70B-instruct-turbo
              - meta-llama-4-maverick
              - mistral-7B-instruct
              - perplexity-sonar
              - rufus
          description: >-
            Filter by a list of sources. Values should be comma separated,
            without brackets or spaces
        - in: query
          name: translate_to_en
          schema:
            type: boolean
          description: >-
            If true, translates clusters and attributes to English. Defaults to
            false.
        - in: path
          name: workspace_id
          schema:
            type: string
            format: uuid
          description: A UUID string identifying the workspace.
          required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeHierarchyTree'
            text/csv:
              schema:
                $ref: '#/components/schemas/AttributeHierarchyTree'
          description: ''
      security:
        - Bearer: []
components:
  schemas:
    AttributeHierarchyTree:
      type: object
      description: Base class with necessary methods overridden
      properties:
        name:
          type: string
        children:
          type: array
          items:
            $ref: '#/components/schemas/AttributeHierarchyCluster'
      required:
        - children
        - name
    AttributeHierarchyCluster:
      type: object
      description: Base class with necessary methods overridden
      properties:
        name:
          type: string
        value:
          type: integer
        children:
          type: array
          items:
            $ref: '#/components/schemas/AttributeHierarchyAttribute'
      required:
        - children
        - name
        - value
    AttributeHierarchyAttribute:
      type: object
      description: Base class with necessary methods overridden
      properties:
        name:
          type: string
        value:
          type: integer
        children:
          type: array
          items:
            $ref: '#/components/schemas/AttributeHierarchyBrand'
      required:
        - children
        - name
        - value
    AttributeHierarchyBrand:
      type: object
      description: Base class with necessary methods overridden
      properties:
        name:
          type: string
        value:
          type: integer
        children:
          type: array
          items:
            $ref: '#/components/schemas/AttributeHierarchySource'
      required:
        - children
        - name
        - value
    AttributeHierarchySource:
      type: object
      description: Base class with necessary methods overridden
      properties:
        name:
          type: string
        value:
          type: integer
      required:
        - name
        - value
  securitySchemes:
    Bearer:
      type: apiKey
      in: header
      name: Authorization

````