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

> Collect web pages that mention a brand, with sentiment and emotion scores, author, date, site type and authority.

# Brand Mentions

Each row is a page somewhere on the web that mentions your query: blog reviews, news coverage, forum threads, product listings. Next to the URL and title you get the passage around the mention, the author when given, the page's language and country, its site type, a positive/negative/neutral sentiment split for the passage, six emotion scores, and authority and spam scores for the page and its domain. Filter to news or forums only with content\_type, and wrap a phrase in double quotes to match it exactly.

```json theme={"dark"}
{
  "query": "notion",
  "results_limit": 100
}
```

Provide a brand, product or topic in query (up to 100 characters). content\_type limits results to news, blogs, message-boards, ecommerce or organization sites. results\_limit defaults to 100 and accepts integers from 1 to 1000. Each request costs 10 credits plus 0.02 credits per page; the 10 credits also apply when no page is found.

## 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 | URL of the page, 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 | URL of the page that mentions the query. |
| `published_at` | `string` | Yes | Time the page was published, in ISO 8601 format, when given. |
| `collected_at` | `string` | No | Time SocQ collected or processed this result, in ISO 8601 format. |
| `title` | `string` | Yes | Title of the page. |
| `text` | `string` | Yes | Passage of the page around the mention. |
| `author_name` | `string` | Yes | Author of the page, when given. |
| `domain` | `string` | Yes | Domain of the page. |
| `language` | `string` | Yes | Language code of the page. |
| `country` | `string` | Yes | Two-letter country code of the site; `WW` means worldwide. |
| `page_types` | `array<string>` | Yes | Kinds of site the page belongs to, such as `news`, `blogs` or `ecommerce`. |
| `sentiment` | `object` | Yes | Sentiment of the passage, as scores from 0 to 1 that add up to 1. |
| `sentiment.positive` | `number` | Yes | Positive score. |
| `sentiment.negative` | `number` | Yes | Negative score. |
| `sentiment.neutral` | `number` | Yes | Neutral score. |
| `emotions` | `object` | Yes | Emotions in the passage, as scores from 0 to 1. |
| `emotions.happiness` | `number` | Yes | Happiness score. |
| `emotions.love` | `number` | Yes | Love score. |
| `emotions.fun` | `number` | Yes | Fun score. |
| `emotions.share` | `number` | Yes | Score for wanting to share. |
| `emotions.sadness` | `number` | Yes | Sadness score. |
| `emotions.anger` | `number` | Yes | Anger score. |
| `content_quality_score` | `integer` | Yes | Quality score of the page's content from 0 to 100. |
| `spam_score` | `integer` | Yes | Spam score of the page from 0 to 100; higher means more signs of spam. |
| `domain_rank` | `integer` | Yes | Authority score of the domain from 0 to 1000. |
| `page_rank` | `integer` | Yes | Authority score of the page from 0 to 1000. |
| `fetched_at` | `string` | Yes | Time the page was last read, in ISO 8601 format. |
| `query` | `string` | Yes | Brand, product or topic that was searched for. |

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-mentions",
    "status": "succeeded",
    "public_id": "brand-monitoring/mentions",
    "result_count": 1,
    "credits_amount": 10.02,
    "results": {
      "limit": 50,
      "next_cursor": null,
      "has_more": false,
      "schema_id": "brand-mention",
      "schema_version": "1.0",
      "items": [
        {
          "id": "https://play.google.com/store/apps/details?id=com.bynge.story&hl=en_US",
          "platform": "brand-monitoring",
          "resource": "mentions",
          "type": "mention",
          "url": "https://play.google.com/store/apps/details?id=com.bynge.story&hl=en_US",
          "published_at": null,
          "collected_at": "2026-11-17T23:55:01.265294Z",
          "title": "Notion Press",
          "text": "Unlock the full potential of your publishing journey with the Notion Press App, offering an enhanced and user-friendly author dashboard. Whether you're tracking your earnings, managing book sales, or utilizing exclusive coupon codes, the Notion Press App is here for you.\nSeamless Author Login: Easily access your Notion Press author account and stay connected with your publishing progress anytime, anywhere.\nEnhanced …",
          "author_name": "Notion Press",
          "domain": "play.google.com",
          "language": "en",
          "country": "WW",
          "page_types": [
            "ecommerce"
          ],
          "sentiment": {
            "positive": 0.3241,
            "negative": 0.1386,
            "neutral": 0.5374
          },
          "emotions": {
            "happiness": 0.3779,
            "love": 0.2316,
            "fun": 0.1624,
            "share": 0.151,
            "sadness": 0.0405,
            "anger": 0.0367
          },
          "content_quality_score": 91,
          "spam_score": 0,
          "domain_rank": 1000,
          "page_rank": 669,
          "fetched_at": "2025-12-28T11:41:43Z",
          "query": "notion"
        }
      ]
    }
  }
}
```


## OpenAPI

````yaml api-manual/agent-api/agent-api.json POST /v1/brand-monitoring/mentions
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/mentions:
    post:
      tags:
        - brand-monitoring
      summary: Brand Mentions API
      description: >-
        Collect the web pages that mention a brand, with sentiment, emotions and
        site authority.
      operationId: socq_brand_monitoring_mentions
      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
                content_type:
                  type: string
                  minLength: 1
                  enum:
                    - blogs
                    - ecommerce
                    - message-boards
                    - news
                    - organization
                  description: >-
                    Kind of site to take mentions from: news, blogs,
                    message-boards, ecommerce or organization.
                query:
                  type: string
                  minLength: 1
                  description: >-
                    Brand, product or topic to look for. Wrap a phrase in double
                    quotes to match it exactly.
                results_limit:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  default: 100
              required:
                - query
              description: >-
                Provide a brand, product or topic in query. Each row is one web
                page that mentions it, with the page's sentiment and emotion
                scores, author, date, site type and authority. results_limit
                defaults to 100 and accepts integers from 1 to 1000.
      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.