> ## Documentation Index > Fetch the complete documentation index at: https://docs.surfacd.com/llms.txt > Use this file to discover all available pages before exploring further. # Matrix Analysis > Returns a metric (visibility, mentions, industry rank, or average position) broken out across two public dimensions. Row, column, and cell identifiers use the same public identifiers as filters: provider strings, country codes, enum values, UUIDs, or stable sentinels. ## OpenAPI ````yaml /openapi.json get /api/v1/projects/{project}/matrix-analysis openapi: 3.1.0 info: title: Surfacd Public API version: 1.0.0 description: >- Public API for Surfacd. Team-scoped operations live under `/api/v1/team/...`; project collections live under `/api/v1/projects`; project-scoped operations live under `/api/v1/projects/{project}/...`. All endpoints require a Bearer team API key created in Team Settings. The API key selects the team for team-level and collection endpoints. servers: - url: https://app.surfacd.com description: Production security: - bearerAuth: [] tags: - name: Projects description: Project management endpoints. Reads only in this version. - name: Prompts description: Prompt management endpoints. Reads only in this version. - name: Team description: Team settings and plan details for the current team. - name: Reporting description: >- Read-only reporting endpoints for projects (brand rankings, mentions, visibility, matrix analysis, source data). - name: Reference description: Reference data used by create, update, and reporting filters. - name: Tags description: Project tag management endpoints. paths: /api/v1/projects/{project}/matrix-analysis: parameters: - $ref: '#/components/parameters/ProjectUuid' get: tags: - Reporting summary: Matrix Analysis description: >- Returns a metric (visibility, mentions, industry rank, or average position) broken out across two public dimensions. Row, column, and cell identifiers use the same public identifiers as filters: provider strings, country codes, enum values, UUIDs, or stable sentinels. operationId: v1ProjectsMatrixAnalysis parameters: - name: row_dimension in: query required: true schema: $ref: '#/components/schemas/DimensionType' - name: column_dimension in: query required: true schema: $ref: '#/components/schemas/DimensionType' description: Must differ from `row_dimension`. - name: metric in: query required: true schema: $ref: '#/components/schemas/MetricType' - name: brands in: query required: false schema: type: array items: type: string format: uuid maxItems: 10 description: Brand UUIDs. Pass repeated `brands[]=...` query params. style: form explode: true - name: tags in: query required: false schema: type: array items: type: string format: uuid description: >- Tag UUID filters. Discover tag UUIDs with `GET /api/v1/projects/{project}/tags`. style: form explode: true - name: services in: query required: false schema: type: array items: type: string description: >- AI platform provider filters such as `chatgpt` or `perplexity`. Discover providers with `GET /api/v1/platforms`. style: form explode: true - name: countries in: query required: false schema: type: array items: type: string description: >- Country code filters such as `US` or `GB`. Discover codes with `GET /api/v1/countries`. style: form explode: true - name: prompt in: query required: false schema: type: string format: uuid description: Prompt UUID filter. - name: topics in: query required: false schema: type: array items: type: string description: >- Topic UUID filters. Use `no_topic` for prompts without a topic. Discover topic UUIDs with `GET /api/v1/projects/{project}/topics`. style: form explode: true - name: start_date in: query required: true schema: type: string format: date - name: end_date in: query required: true schema: type: string format: date description: Must be on or after `start_date`. - name: competitors_only in: query required: false schema: type: boolean description: >- When true, brand dimensions only include the primary brand and marked competitors. responses: '200': description: Matrix analysis result. content: application/json: schema: $ref: '#/components/schemas/MatrixAnalysis' '422': $ref: '#/components/responses/ValidationError' components: parameters: ProjectUuid: name: project in: path required: true description: Project UUID. schema: type: string format: uuid schemas: DimensionType: type: string enum: - brand - tag - country - service - topic MetricType: type: string enum: - industry_rank - visibility - mentions - avg_position MatrixAnalysis: type: object properties: row_dimension_type: $ref: '#/components/schemas/DimensionType' column_dimension_type: $ref: '#/components/schemas/DimensionType' metric_type: $ref: '#/components/schemas/MetricType' rows: type: array items: $ref: '#/components/schemas/MatrixRow' columns: type: array items: $ref: '#/components/schemas/MatrixColumn' required: - row_dimension_type - column_dimension_type - metric_type - rows - columns MatrixRow: type: object properties: id: type: string description: >- Public identifier for this dimension value: service provider, country code, category value, topic/tag/brand UUID, or a stable sentinel such as `untagged` / `no_topic`. name: type: string metadata: type: - object - 'null' additionalProperties: true cells: type: array items: $ref: '#/components/schemas/MatrixCell' required: - id - name - metadata - cells MatrixColumn: type: object properties: id: type: string description: >- Public identifier for this dimension value: service provider, country code, category value, topic/tag/brand UUID, or a stable sentinel such as `untagged` / `no_topic`. name: type: string metadata: type: - object - 'null' additionalProperties: true required: - id - name ValidationError: type: object description: Returned when one or more request parameters fail validation. properties: message: type: string errors: type: object additionalProperties: type: array items: type: string required: - message - errors MatrixCell: type: object properties: column_id: type: string description: Public identifier matching the related column `id`. column_name: type: string value: type: - number - 'null' format: float comparison_value: type: - number - 'null' format: float change: type: - number - 'null' format: float change_percentage: type: - number - 'null' format: float is_positive_good: type: boolean description: >- True when a larger value is favourable (e.g. visibility); false when a smaller value is favourable (e.g. rank). required: - column_id - column_name - value - comparison_value - change - change_percentage - is_positive_good responses: ValidationError: description: Validation failed. content: application/json: schema: $ref: '#/components/schemas/ValidationError' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: token description: >- Team API key created in Team Settings. Use it with URLs for the same team. ````