# Content Analysis (/docs/content_analysis)

Cross-web brand-mention and sentiment intelligence. Find every web citation of a keyword, scored on a 6-axis emotional sentiment model, with totals, histograms, and trends over time.

Web-wide brand listening and sentiment intelligence. Search every web page (news, blogs, ecommerce, message boards, organization sites) that mentions a keyword, each scored on a 6-axis emotional model (anger, happiness, love, sadness, share, fun) plus positive, negative and neutral probabilities, then roll it up into totals, top domains, rating histograms, and sentiment over time.

Base URL: `/v1/content_analysis/...`

  The six keyword-driven endpoints are **20 credits each**, a flat cost that
  overrides the tier ladder price. The four taxonomy endpoints are 1 credit.
  Budget on the endpoint, not the tier.

## Quickstart

### 1. Take the roll-up first

`summary` is the right first call on any new keyword: one object describing its whole web presence.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/content_analysis/summary?keyword=openai" \
  -H "x-api-key: YOUR_API_KEY"
```

### 2. Drop into the individual mentions

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/content_analysis/search?keyword=openai&page_type=news,blogs&limit=50" \
  -H "x-api-key: YOUR_API_KEY"
```

## Pick the endpoint by the shape of the answer

All six keyword endpoints read the same citation index. They differ in what they hand back, and because each is a full 20-credit call, choosing the right one matters more here than on most platforms.

| Endpoint                                       | Credits | What it returns                                                                                                                 | Key parameters                                                                                                                 |
| ---------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `GET /v1/content_analysis/summary`             | 20      | Total mention count, top domains, sentiment splits, and breakdowns by page type, country and language                           | `keyword`, `page_type`, `positive_connotation_threshold`, `sentiments_connotation_threshold`, `internal_list_limit`, `filters` |
| `GET /v1/content_analysis/search`              | 20      | The individual mentions, each with its page, snippet and per-mention sentiment scores                                           | `keyword`, `page_type`, `search_mode`, `limit` (1-100, default 10), `cursor`, `order_by`, `filters`                            |
| `GET /v1/content_analysis/sentiment`           | 20      | The sentiment breakdown alone: the positive/negative/neutral split and the six emotional axes, with no domains or geography     | `keyword`, `page_type`, `positive_connotation_threshold`, `filters`                                                            |
| `GET /v1/content_analysis/rating-distribution` | 20      | A ten-bucket histogram of the star ratings found in the mentions, with the sentiment, domains and categories inside each bucket | `keyword`, `page_type`, `filters`                                                                                              |
| `GET /v1/content_analysis/phrase-trends`       | 20      | Mention volume and sentiment as a time series for one keyword                                                                   | `keyword`, `date_from` (required), `date_to`, `date_group`, `page_type`, `internal_list_limit`, `filters`                      |
| `GET /v1/content_analysis/category-trends`     | 20      | The same time series for a whole content category rather than a keyword                                                         | `category_code` (required), `date_from` (required), `date_to`, `date_group`, `internal_list_limit`, `filters`                  |

On `search`, `search_mode=one_per_domain` collapses to the single strongest page per domain, which is what you want when one site is flooding the results. `as_is` (the default) returns everything. On the trend endpoints, `date_to` defaults to today and `date_group` buckets by `day`, `week` or `month` (default `month`).

`rating-distribution` answers "how does the language differ between the people who rated this well and the people who rated it badly", which is a review-heavy, product-shaped question.

```bash title="cURL"
# Weekly mention volume and sentiment for a brand across six months
curl "https://www.socialcrawl.dev/v1/content_analysis/phrase-trends?keyword=notion&date_from=2026-02-01&date_group=week" \
  -H "x-api-key: YOUR_API_KEY"
```

## Describe the index

These four describe the index rather than query it, cost 1 credit each, and are worth calling once and caching.

| Endpoint                              | Credits | What it returns                                                         | Key parameters |
| ------------------------------------- | ------- | ----------------------------------------------------------------------- | -------------- |
| `GET /v1/content_analysis/categories` | 1       | The full category taxonomy with each entry's code, name and parent      | none           |
| `GET /v1/content_analysis/languages`  | 1       | The supported language codes, for reading a mention's `language` field  | none           |
| `GET /v1/content_analysis/locations`  | 1       | The supported locations, for reading a mention's `country` field        | none           |
| `GET /v1/content_analysis/filters`    | 1       | The fields you are allowed to filter on and the value type each accepts | none           |

`categories` is where the `category_code` that `category-trends` requires comes from, and it also decodes the numeric category values attached to individual mentions.

```bash title="cURL"
# 1. Find the category code
curl "https://www.socialcrawl.dev/v1/content_analysis/categories" \
  -H "x-api-key: YOUR_API_KEY"

# 2. Trend that whole category
curl "https://www.socialcrawl.dev/v1/content_analysis/category-trends?category_code=10021&date_from=2026-01-01" \
  -H "x-api-key: YOUR_API_KEY"
```

## Advanced filtering

Beyond `page_type`, all six analytic endpoints (the five keyword endpoints and `category-trends`) accept `filters`, a filter expression passed as a JSON array of up to eight conditions. Call `filters` first to see which fields are filterable and what each expects. When both `filters` and `page_type` are present they are combined with `AND`. On the aggregate endpoints the filter is applied before anything is counted, so `filters=[["country","=","DE"]]` on `category-trends` returns buckets built only from German-hosted citations, and `[["language","=","de"]]` does the same for German-language ones.

Without a filter, every trend bucket covers citations from all countries. Its `countries` and `languages` maps are the breakdown of that bucket, not a list of markets you asked for.

`search` additionally accepts `order_by` as `"field,direction"` pairs separated by `;`, so `order_by=content_info.sentiment_connotations.anger,desc` surfaces the angriest mentions first.

Two thresholds control how mentions are bucketed rather than which are returned. `positive_connotation_threshold` (0-1, default 0.4) sets the probability at which a mention counts as positive, and `sentiments_connotation_threshold` does the same for the six emotional buckets on `summary`. Raise them for a stricter read, lower them if the neutral bucket is swallowing everything.

## All endpoints

## Platform notes

- **Escape quotes for exact phrases.** `keyword` matches loosely by default. Wrap the term in escaped double quotes (`keyword="logitech mouse"`) to match the phrase rather than the words.
- **`internal_list_limit` caps the arrays inside a response**, such as `top_domains` and `categories` on `summary` or the per-bucket lists on the trend endpoints. It runs 1-20 and does not change the price.
- **This index is not the social platforms.** A page that quotes a tweet is a citation. The tweet itself is not. For native platform posts use the per-platform endpoints or [universal search](/docs/search/everywhere.md).
- **This is page-level web citation data, not native platform posts.** Sentiment values are model-derived NLP from the upstream index, passed through verbatim.
- **Only `search` paginates**, with the `cursor` returned as `next_cursor`. The aggregate endpoints return one object per call.
- `phrase-trends` and `category-trends` both require `date_from` and reject a range they cannot bucket, before billing.
- Narrow any keyword query to a page type with `page_type` (`news`, `blogs`, `ecommerce`, `message-boards`, `organization`, comma-separated for several).

## Next steps

- [Prism](/docs/prism.md): brand-mentions and crisis-radar build on this index.
- [Universal search](/docs/search/everywhere.md): Native platform posts, where this index only has citations.
- [Endpoint pricing](/docs/endpoint-pricing.md): The full registry-derived cost table.