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

# Social Pulse

> Monitor social media conversations and trending topics related to prediction markets.

**Endpoint:** `POST /v2/semantic/retrieve/parameterized`\
**Authentication:** Bearer token

## Query parameters

All requests use `agent_id` `585` (Social Pulse). Set filters inside `params` in the playground — all values must be strings. Use `pagination` for page size and offset (integers, not strings).

| Parameter | Type | Description |
| - | - | - |
| `keywords` | String | Keyword filter set (for example, `"{NHL,hockey,Stanley Cup}"`). |
| `hours_back` | String | How many hours back to search (for example, `"12"`). |
| `pagination.limit` | Integer | Maximum records per request (`1`–`200`; default `10`). |
| `pagination.offset` | Integer | Records to skip before returning results (default `0`). |

## Example Request

```bash cURL theme={null}
curl --request POST \
  --url https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "agent_id": 585,
  "params": {
    "keywords": "{NHL,hockey,Stanley Cup}",
    "hours_back": "12"
  },
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "formatter_config": {
    "format_type": "raw"
  }
}'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
    "agent_id": 585,
    "params": {
        "keywords": "{NHL,hockey,Stanley Cup}",
        "hours_back": "12"
    },
    "pagination": {
        "limit": 10,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}
)

print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch("https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "agent_id": 585,
  "params": {
    "keywords": "{NHL,hockey,Stanley Cup}",
    "hours_back": "12"
  },
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "formatter_config": {
    "format_type": "raw"
  }
})
});

const data = await response.json();
```

## Top-Level Fields

| Field | Type | Description |
| - | - | - |
| `timestamp` | String | Timestamp of the response (may be empty) |
| `params` | Object | Echo of the query parameters used |
| `pagination` | Object | Pagination metadata for the result set |
| `data.results` | Array | List of matching social media posts |

## `pagination` Object

| Field | Type | Description |
| - | - | - |
| `limit` | Integer | Maximum number of results returned (default: `200`) |
| `offset` | Integer | Offset for paginated results |
| `has_more` | Boolean | Whether additional results are available beyond this page |

## `data.results[]` — Individual post object

| Field | Type | Description |
| - | - | - |
| `id` | Integer | Unique identifier of the post |
| `content` | String | Full text content of the tweet |
| `username` | String | Twitter/X handle of the author |
| `url` | String | Direct URL to the post on X (Twitter) |
| `created_on` | String (ISO 8601) | Timestamp when the post was created |
| `like_count` | Integer | Number of likes on the post |
| `retweet_count` | Integer | Number of retweets |
| `reply_count` | Integer | Number of replies |
| `quote_count` | Integer | Number of quote tweets |
| `tweet_count` | Integer | Total tweet volume associated with the keyword cluster |
| `acceleration` | String | Rate of growth in social activity for the keyword cluster |
| `author_diversity_pct` | String | Percentage of unique authors contributing to the trend |
| `pct_last_1h` | String | Percentage of total activity occurring in the last 1 hour |
| `pct_last_6h` | String | Percentage of total activity occurring in the last 6 hours |


## OpenAPI

````yaml /api-reference/social-pulse.openapi.json POST /api/v2/semantic/retrieve/parameterized
openapi: 3.1.0
info:
  title: Falcon API — Social Pulse
  version: 1.0.0
servers:
  - url: https://narrative.agent.heisenberg.so
    description: Production
security:
  - bearerAuth: []
paths:
  /api/v2/semantic/retrieve/parameterized:
    post:
      tags:
        - Social Intelligence
      summary: Social Pulse
      description: >-
        Monitor social media conversations and trending topics related to
        prediction markets.
      operationId: socialPulse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SocialPulseRequest'
            examples:
              default:
                summary: NHL-related posts from the last 12 hours
                value:
                  agent_id: 585
                  params:
                    keywords: '{NHL,hockey,Stanley Cup}'
                    hours_back: '12'
                  pagination:
                    limit: 10
                    offset: 0
                  formatter_config:
                    format_type: raw
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SocialPulseResponse'
        '400':
          description: Bad request — check params
        '401':
          description: Unauthorized — check your Bearer token
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            curl --request POST \
              --url https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized \
              --header 'Authorization: Bearer YOUR_TOKEN' \
              --header 'Content-Type: application/json' \
              --data '{
              "agent_id": 585,
              "params": {
                "keywords": "{NHL,hockey,Stanley Cup}",
                "hours_back": "12"
              },
              "pagination": { "limit": 10, "offset": 0 },
              "formatter_config": { "format_type": "raw" }
            }'
        - lang: python
          label: Python
          source: |-
            import requests

            response = requests.post(
                "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
                headers={"Authorization": "Bearer YOUR_TOKEN"},
                json={
                    "agent_id": 585,
                    "params": {
                        "keywords": "{NHL,hockey,Stanley Cup}",
                        "hours_back": "12",
                    },
                    "pagination": {"limit": 10, "offset": 0},
                    "formatter_config": {"format_type": "raw"},
                },
            )

            print(response.json())
        - lang: javascript
          label: JavaScript
          source: |-
            const response = await fetch(
              "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
              {
                method: "POST",
                headers: {
                  Authorization: "Bearer YOUR_TOKEN",
                  "Content-Type": "application/json",
                },
                body: JSON.stringify({
                  agent_id: 585,
                  params: {
                    keywords: "{NHL,hockey,Stanley Cup}",
                    hours_back: "12",
                  },
                  pagination: { limit: 10, offset: 0 },
                  formatter_config: { format_type: "raw" },
                }),
              }
            );

            const data = await response.json();
components:
  schemas:
    SocialPulseRequest:
      type: object
      required:
        - params
      properties:
        agent_id:
          type: integer
          enum:
            - 585
          default: 585
          x-default: 585
          description: Social Pulse agent ID.
        params:
          $ref: '#/components/schemas/SocialPulseParams'
        pagination:
          $ref: '#/components/schemas/SocialPulsePagination'
        formatter_config:
          $ref: '#/components/schemas/SocialPulseFormatterConfig'
    SocialPulseResponse:
      type: object
      readOnly: true
      properties:
        timestamp:
          type: string
          readOnly: true
        params:
          $ref: '#/components/schemas/SocialPulseResponseParams'
        pagination:
          type: object
          readOnly: true
          properties:
            limit:
              type: integer
              readOnly: true
            offset:
              type: integer
              readOnly: true
            has_more:
              type: boolean
              readOnly: true
        data:
          type: object
          readOnly: true
          properties:
            results:
              type: array
              readOnly: true
              items:
                type: object
                readOnly: true
                additionalProperties: true
        request_id:
          type: string
          readOnly: true
    SocialPulseParams:
      type: object
      description: Filter parameters. All values must be strings.
      additionalProperties: false
      required:
        - keywords
        - hours_back
      properties:
        keywords:
          type: string
          default: '{NHL,hockey,Stanley Cup}'
          description: Keyword filter set (for example, "{NHL,hockey,Stanley Cup}").
        hours_back:
          type: string
          default: '12'
          description: How many hours back to search (for example, "12").
    SocialPulsePagination:
      type: object
      properties:
        limit:
          type: integer
          minimum: 1
          maximum: 200
          default: 10
          description: Maximum number of records returned per request.
        offset:
          type: integer
          minimum: 0
          default: 0
          description: Number of records to skip before returning results.
    SocialPulseFormatterConfig:
      type: object
      properties:
        format_type:
          type: string
          enum:
            - raw
          default: raw
          description: Output format. Use "raw" for structured JSON.
    SocialPulseResponseParams:
      type: object
      readOnly: true
      properties:
        keywords:
          type: string
          readOnly: true
        hours_back:
          type: string
          readOnly: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your Falcon API key from the dashboard

````

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