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

# Brand Sentiment Analysis

> Split the web pages that mention a brand into positive, negative and neutral, and by emotion, with the top sites and countries for each.

# Brand Sentiment Analysis

One number answers "how does the web feel about us", and this endpoint gives you the breakdown behind it. Pages mentioning your query are grouped by their main sentiment and, separately, by their strongest emotion: happiness, love, fun, share, sadness and anger. Each group reports how many pages it holds and the sites, countries, languages and site types that contribute most, so you can tell whether criticism comes from news outlets or from a single forum.

```json theme={"dark"}
{
  "query": "notion"
}
```

Provide a brand, product or topic in query (up to 100 characters). Each request costs 10 credits and returns one row. Very broad terms with millions of mentions take longer to analyze, up to a few minutes.

## Standard Result Fields

Task results use the stable SocQ fields below. Source-specific field names and formats are normalized without inferring or enriching values that the source did not provide. To request a smaller field set, use `fields` for MCP queries, `_result_fields` for typed tools, or `--result-fields` in the CLI. Declared fields remain present when their value is `null`.

| Field | Type | Nullable | Description |
| - | - | - | - |
| `id` | `string` | Yes | The query, used as the identifier. |
| `platform` | `string` | No | Platform the result belongs to, such as `instagram` or `linkedin`. |
| `resource` | `string` | No | SocQ resource represented by the result, such as `videos` or `comments`. |
| `type` | `string` | No | Category of the result item, such as `video`, `post`, or `comment`. |
| `url` | `string` | Yes | Public URL of the result item when available. |
| `published_at` | `string` | Yes | Time the source item was published, in ISO 8601 format when available. |
| `collected_at` | `string` | No | Time SocQ collected or processed this result, in ISO 8601 format. |
| `query` | `string` | Yes | Brand, product or topic that was analyzed. |
| `sentiments` | `array<object>` | Yes | Pages mentioning the query, grouped by their main sentiment. |
| `sentiments.label` | `string` | Yes | Sentiment of the group: `positive`, `negative` or `neutral`. |
| `sentiments.mentions_count` | `integer` | Yes | Number of web pages in this group. |
| `sentiments.top_domains` | `array<object>` | Yes | Sites with the most pages in this group, largest first. |
| `sentiments.top_domains.name` | `string` | Yes | Domain of the site. |
| `sentiments.top_domains.count` | `integer` | Yes | Number of web pages. |
| `sentiments.countries` | `array<object>` | Yes | Countries of the pages in this group, largest first. |
| `sentiments.countries.name` | `string` | Yes | Two-letter country code; `WW` means worldwide. |
| `sentiments.countries.count` | `integer` | Yes | Number of web pages. |
| `sentiments.languages` | `array<object>` | Yes | Languages of the pages in this group, largest first. |
| `sentiments.languages.name` | `string` | Yes | Language code, such as `en`. |
| `sentiments.languages.count` | `integer` | Yes | Number of web pages. |
| `sentiments.page_types` | `array<object>` | Yes | Kinds of sites the pages come from, largest first. |
| `sentiments.page_types.name` | `string` | Yes | Site kind: `news`, `blogs`, `message-boards`, `ecommerce` or `organization`. |
| `sentiments.page_types.count` | `integer` | Yes | Number of web pages. |
| `emotions` | `array<object>` | Yes | Pages mentioning the query, grouped by their strongest emotion. |
| `emotions.label` | `string` | Yes | Emotion of the group: `happiness`, `love`, `fun`, `share`, `sadness` or `anger`. |
| `emotions.mentions_count` | `integer` | Yes | Number of web pages in this group. |
| `emotions.top_domains` | `array<object>` | Yes | Sites with the most pages in this group, largest first. |
| `emotions.top_domains.name` | `string` | Yes | Domain of the site. |
| `emotions.top_domains.count` | `integer` | Yes | Number of web pages. |
| `emotions.countries` | `array<object>` | Yes | Countries of the pages in this group, largest first. |
| `emotions.countries.name` | `string` | Yes | Two-letter country code; `WW` means worldwide. |
| `emotions.countries.count` | `integer` | Yes | Number of web pages. |
| `emotions.languages` | `array<object>` | Yes | Languages of the pages in this group, largest first. |
| `emotions.languages.name` | `string` | Yes | Language code, such as `en`. |
| `emotions.languages.count` | `integer` | Yes | Number of web pages. |
| `emotions.page_types` | `array<object>` | Yes | Kinds of sites the pages come from, largest first. |
| `emotions.page_types.name` | `string` | Yes | Site kind: `news`, `blogs`, `message-boards`, `ecommerce` or `organization`. |
| `emotions.page_types.count` | `integer` | Yes | Number of web pages. |

The following example shows the response format for a completed task. Actual data depends on your query.

## Completed Task Response

```json theme={"dark"}
{
  "code": 200,
  "data": {
    "task_id": "example-brand-monitoring-sentiment",
    "status": "succeeded",
    "public_id": "brand-monitoring/sentiment",
    "result_count": 1,
    "credits_amount": 10,
    "results": {
      "limit": 50,
      "next_cursor": null,
      "has_more": false,
      "schema_id": "brand-sentiment",
      "schema_version": "1.0",
      "items": [
        {
          "id": "notion",
          "platform": "brand-monitoring",
          "resource": "sentiment",
          "type": "sentiment",
          "url": null,
          "published_at": null,
          "collected_at": "2026-11-17T23:56:20.984740Z",
          "query": "notion",
          "sentiments": [
            {
              "label": "positive",
              "mentions_count": 3890592,
              "top_domains": [
                {
                  "name": "oychicago.com",
                  "count": 55456
                },
                {
                  "name": "bibleandbookcenter.com",
                  "count": 39000
                },
                {
                  "name": "the-jet-collection.com",
                  "count": 26240
                }
              ],
              "countries": [
                {
                  "name": "US",
                  "count": 576952
                },
                {
                  "name": "FR",
                  "count": 318248
                },
                {
                  "name": "WW",
                  "count": 183904
                }
              ],
              "languages": [
                {
                  "name": "en",
                  "count": 3071912
                },
                {
                  "name": "fr",
                  "count": 689568
                },
                {
                  "name": "es",
                  "count": 59640
                }
              ],
              "page_types": [
                {
                  "name": "blogs",
                  "count": 2738408
                },
                {
                  "name": "organization",
                  "count": 1192344
                },
                {
                  "name": "news",
                  "count": 602184
                }
              ]
            },
            {
              "label": "negative",
              "mentions_count": 4000000,
              "top_domains": [
                {
                  "name": "oychicago.com",
                  "count": 50928
                },
                {
                  "name": "acedessays.com",
                  "count": 46656
                },
                {
                  "name": "integrately.com",
                  "count": 35688
                }
              ],
              "countries": [
                {
                  "name": "US",
                  "count": 837792
                },
                {
                  "name": "FR",
                  "count": 359008
                },
                {
                  "name": "WW",
                  "count": 181512
                }
              ],
              "languages": [
                {
                  "name": "en",
                  "count": 3222480
                },
                {
                  "name": "fr",
                  "count": 685728
                },
                {
                  "name": "de",
                  "count": 34240
                }
              ],
              "page_types": [
                {
                  "name": "blogs",
                  "count": 2728320
                },
                {
                  "name": "organization",
                  "count": 1167856
                },
                {
                  "name": "news",
                  "count": 1141824
                }
              ]
            },
            {
              "label": "neutral",
              "mentions_count": 3928936,
              "top_domains": [
                {
                  "name": "oychicago.com",
                  "count": 73112
                },
                {
                  "name": "cebh.info",
                  "count": 47720
                },
                {
                  "name": "visualbudget.org",
                  "count": 43824
                }
              ],
              "countries": [
                {
                  "name": "US",
                  "count": 643752
                },
                {
                  "name": "WW",
                  "count": 144488
                },
                {
                  "name": "IN",
                  "count": 116192
                }
              ],
              "languages": [
                {
                  "name": "en",
                  "count": 3917480
                },
                {
                  "name": "fr",
                  "count": 2832
                },
                {
                  "name": "de",
                  "count": 2144
                }
              ],
              "page_types": [
                {
                  "name": "blogs",
                  "count": 3166704
                },
                {
                  "name": "organization",
                  "count": 1120616
                },
                {
                  "name": "news",
                  "count": 480624
                }
              ]
            }
          ],
          "emotions": [
            {
              "label": "happiness",
              "mentions_count": 687456,
              "top_domains": [
                {
                  "name": "euskalerriairratia.eus",
                  "count": 41136
                },
                {
                  "name": "eurostarinc.com",
                  "count": 25168
                },
                {
                  "name": "integrately.com",
                  "count": 15376
                }
              ],
              "countries": [
                {
                  "name": "FR",
                  "count": 229448
                },
                {
                  "name": "WW",
                  "count": 79600
                },
                {
                  "name": "US",
                  "count": 42960
                }
              ],
              "languages": [
                {
                  "name": "fr",
                  "count": 531200
                },
                {
                  "name": "en",
                  "count": 109272
                },
                {
                  "name": "de",
                  "count": 27984
                }
              ],
              "page_types": [
                {
                  "name": "blogs",
                  "count": 433944
                },
                {
                  "name": "organization",
                  "count": 292072
                },
                {
                  "name": "ecommerce",
                  "count": 172496
                }
              ]
            },
            {
              "label": "love",
              "mentions_count": 256208,
              "top_domains": [
                {
                  "name": "bloomex.ca",
                  "count": 9576
                },
                {
                  "name": "scripturesavvy.com",
                  "count": 2992
                },
                {
                  "name": "explainingthebible.com",
                  "count": 2656
                }
              ],
              "countries": [
                {
                  "name": "US",
                  "count": 45768
                },
                {
                  "name": "FR",
                  "count": 33984
                },
                {
                  "name": "WW",
                  "count": 15176
                }
              ],
              "languages": [
                {
                  "name": "en",
                  "count": 183144
                },
                {
                  "name": "fr",
                  "count": 66024
                },
                {
                  "name": "de",
                  "count": 3240
                }
              ],
              "page_types": [
                {
                  "name": "blogs",
                  "count": 155704
                },
                {
                  "name": "organization",
                  "count": 114448
                },
                {
                  "name": "news",
                  "count": 61496
                }
              ]
            },
            {
              "label": "fun",
              "mentions_count": 30032,
              "top_domains": [
                {
                  "name": "ariase.com",
                  "count": 4296
                },
                {
                  "name": "vin-vigne.com",
                  "count": 3640
                },
                {
                  "name": "conseilinformatique.fr",
                  "count": 768
                }
              ],
              "countries": [
                {
                  "name": "FR",
                  "count": 18648
                },
                {
                  "name": "WW",
                  "count": 1472
                },
                {
                  "name": "US",
                  "count": 816
                }
              ],
              "languages": [
                {
                  "name": "fr",
                  "count": 25520
                },
                {
                  "name": "en",
                  "count": 2288
                },
                {
                  "name": "ja",
                  "count": 1256
                }
              ],
              "page_types": [
                {
                  "name": "blogs",
                  "count": 18152
                },
                {
                  "name": "organization",
                  "count": 16488
                },
                {
                  "name": "ecommerce",
                  "count": 8976
                }
              ]
            }
          ]
        }
      ]
    }
  }
}
```


## OpenAPI

````yaml api-manual/agent-api/agent-api.json POST /v1/brand-monitoring/sentiment
openapi: 3.1.0
info:
  title: SocQ Agent API
  version: v1-87892a6484c2
  description: Asynchronous social data API generated from the SocQ Capability Registry.
servers:
  - url: https://api.socq.ai
security: []
paths:
  /v1/brand-monitoring/sentiment:
    post:
      tags:
        - brand-monitoring
      summary: Brand Sentiment Analysis API
      description: >-
        Break down the sentiment and emotions of the web pages that mention a
        brand.
      operationId: socq_brand_monitoring_sentiment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $schema: https://json-schema.org/draft/2020-12/schema
              type: object
              additionalProperties: false
              properties:
                callback_url:
                  type: string
                  format: uri
                query:
                  type: string
                  minLength: 1
                  description: >-
                    Brand, product or topic to look for. Wrap a phrase in double
                    quotes to match it exactly.
              required:
                - query
              description: >-
                Provide a brand, product or topic in query. The result is one
                row splitting the web pages that mention it by sentiment
                (positive, negative, neutral) and by emotion, with the leading
                sites and countries for each.
      responses:
        '200':
          description: Task accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentSubmitResponse'
        '422':
          description: Input validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentValidationErrorResponse'
      security:
        - bearerAuth: []
        - apiKeyAuth: []
components:
  schemas:
    AgentSubmitResponse:
      type: object
      properties:
        code:
          type: integer
          const: 200
        data:
          type: object
          properties:
            task_id:
              type: string
            status:
              type: string
            created_time:
              type:
                - string
                - 'null'
          required:
            - task_id
            - status
    AgentValidationErrorResponse:
      type: object
      properties:
        code:
          type: integer
          const: 422
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
            details:
              type: object
          required:
            - message
            - type
      required:
        - code
        - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

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