> For the complete documentation index, see [llms.txt](https://falcon-bot.gitbook.io/falcon-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://falcon-bot.gitbook.io/falcon-api/market-intelligence/social-pulse.md).

# Social Pulse

### Request Body (JSON)

```bash
{
    "agent_id": 585,
    "params": {
        "keywords": "{NHL,hockey,Stanley Cup}",
        "hours_back": "12"
    },
    "formatter_config": {
        "format_type": "raw"
    }
}
```

***

### Request Body

| Field                          | Type    | Required | Description                       |
| ------------------------------ | ------- | -------- | --------------------------------- |
| `agent_id`                     | Integer | Yes      | ID of the retrieval agent         |
| `params`                       | Object  | Yes      | Query parameters                  |
| `params.keywords`              | String  | Yes      | Keywords enclosed in curly braces |
| `params.hours_back`            | String  | Yes      | Number of hours to look back      |
| `formatter_config`             | Object  | Yes      | Response formatting configuration |
| `formatter_config.format_type` | String  | Yes      | Output format (`raw` supported)   |

<details>

<summary>Example Request</summary>

```bash
curl --location '/v2/semantic/retrieve/parameterized' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
    "agent_id": 585,
    "params": {
        "keywords": "{Trump,election,MAGA}",
        "hours_back": "12"
    },
    "formatter_config": {
        "format_type": "raw"
    }
}'
```

</details>

***

### Response Fields

#### Top-Level Fields

| Field          | Type   | Description               |
| -------------- | ------ | ------------------------- |
| `timestamp`    | String | Timestamp of the response |
| `params`       | Object | Echo of query parameters  |
| `pagination`   | Object | Pagination metadata       |
| `data.results` | Array  | List of matching posts    |

***

#### `Pagination` Object

| Field      | Type    | Description                      |
| ---------- | ------- | -------------------------------- |
| `limit`    | Integer | Maximum results returned         |
| `offset`   | Integer | Pagination offset                |
| `has_more` | Boolean | Whether additional results exist |

***

#### `data.results[]` — Individual Post Object

| Field                  | Type    | Description                                |
| ---------------------- | ------- | ------------------------------------------ |
| `id`                   | Integer | Post identifier                            |
| `content`              | String  | Full text of the post                      |
| `username`             | String  | Author handle                              |
| `url`                  | String  | Direct link to the post                    |
| `created_on`           | String  | Timestamp of the post                      |
| `like_count`           | Integer | Number of likes                            |
| `retweet_count`        | Integer | Number of reposts                          |
| `reply_count`          | Integer | Number of replies                          |
| `quote_count`          | Integer | Number of quote posts                      |
| `tweet_count`          | Integer | Total tweet volume for the keyword cluster |
| `acceleration`         | String  | Rate of growth in social activity          |
| `author_diversity_pct` | String  | Percentage of unique authors               |
| `pct_last_1h`          | String  | Share of activity in the last hour         |
| `pct_last_6h`          | String  | Share of activity in the last 6 hours      |

***

### Notes

* Use `params.keywords` to target **specific topics, markets, or events**. Multiple keywords can be combined to refine the signal.
* Adjust `params.hours_back` to control the **time window of analysis**, with smaller windows surfacing rapidly emerging trends.
* Monitor the `acceleration` metric to identify **topics gaining traction quickly**, which can signal emerging narratives.
* Use `author_diversity_pct` to distinguish **organic trends from coordinated or low-diversity activity**.
* Compare `tweet_count`, `retweet_count`, and `like_count` to evaluate **engagement strength and reach** of a topic.
* Use pagination (`limit` and `offset`) when retrieving large result sets to **scan deeper into historical or high-volume discussions**.
* Combine social activity metrics with market data to detect **early signals that may precede market movement**.