Skip to main content
POST
/
v2
/
geo
/
reports
/
sentiments
Get Sentiment Report
curl --request POST \
  --url https://api.writesonic.com/v2/geo/reports/sentiments \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "project_id": "<string>",
  "dimensions": [
    "topic"
  ],
  "start_date": "2023-11-07T05:31:56Z",
  "end_date": "2023-11-07T05:31:56Z",
  "order_by": [
    {
      "field": "<string>",
      "order": "asc"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "measures": [
    "total_keyword_occurrences"
  ],
  "filters": {
    "topics": {
      "condition": "AND",
      "items": [
        {
          "operator": "is",
          "value": "<unknown>"
        }
      ]
    },
    "prompts": {
      "condition": "AND",
      "items": [
        {
          "operator": "is",
          "value": "<unknown>"
        }
      ]
    },
    "tags": {
      "condition": "AND",
      "items": [
        {
          "operator": "is",
          "value": "<unknown>"
        }
      ]
    },
    "markets": {
      "condition": "AND",
      "items": [
        {
          "operator": "is",
          "value": "<unknown>"
        }
      ]
    },
    "intent": {
      "condition": "AND",
      "items": [
        {
          "operator": "is",
          "value": "<unknown>"
        }
      ]
    },
    "branded": {
      "condition": "AND",
      "items": [
        {
          "operator": "is",
          "value": "<unknown>"
        }
      ]
    },
    "platform": {
      "condition": "AND",
      "items": [
        {
          "operator": "is",
          "value": "<unknown>"
        }
      ]
    },
    "has_shopping_card": {
      "condition": "AND",
      "items": [
        {
          "operator": "is",
          "value": "<unknown>"
        }
      ]
    },
    "visibility": {
      "condition": "AND",
      "items": [
        {
          "operator": "eq",
          "value": "<unknown>"
        }
      ]
    },
    "rank": {
      "condition": "AND",
      "items": [
        {
          "operator": "eq",
          "value": "<unknown>"
        }
      ]
    },
    "website_mentioned_in_answer": {
      "condition": "AND",
      "items": [
        {
          "operator": "is",
          "value": "<unknown>"
        }
      ]
    },
    "cited_page_url": {
      "condition": "AND",
      "items": [
        {
          "operator": "is",
          "value": "<unknown>"
        }
      ]
    },
    "cited_domain": {
      "condition": "AND",
      "items": [
        {
          "operator": "is",
          "value": "<unknown>"
        }
      ]
    },
    "website_mentioned_in_citation": {
      "condition": "AND",
      "items": [
        {
          "operator": "is",
          "value": "<unknown>"
        }
      ]
    },
    "status": {
      "condition": "AND",
      "items": [
        {
          "operator": "is",
          "value": "<unknown>"
        }
      ]
    }
  },
  "date_aggregation_interval": "day",
  "website_type": "SELF"
}
'
{
  "info": {
    "total_rows": 123,
    "query": {
      "metrics": [
        "<string>"
      ],
      "start_date": "2023-11-07T05:31:56Z",
      "end_date": "2023-11-07T05:31:56Z",
      "order_by": {},
      "pagination": {},
      "filters": {}
    }
  },
  "data": [
    {
      "topic_id": "<string>",
      "topic_name": "<string>",
      "tag_id": "<string>",
      "tag_name": "<string>",
      "market_id": "<string>",
      "market_name": "<string>",
      "model_id": "<string>",
      "model_name": "<string>",
      "query_id": "<string>",
      "query_name": "<string>",
      "date": "<string>",
      "website_id": "<string>",
      "website_name": "<string>",
      "total_keyword_occurrences": 123,
      "total_positive_keyword_occurrences": 123,
      "unique_positive_keywords": 123,
      "total_unique_keywords": 123,
      "positive_subtheme_count": 123,
      "negative_subtheme_count": 123
    }
  ]
}

Authorizations

​
X-API-KEY
string
header
required

Body

application/json

Request parameters for the Sentiment Report API.

​
project_id
string
required

Unique identifier of the project to query.

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
dimensions
enum<string>[]
required

Dimensions to group sentiment data by. At least one dimension is required.

Minimum array length: 1

Dimensions to group report data by.

  • topic: Group by topic/category
  • tag: Group by tag
  • market: Group by market/region
  • model: Group by AI model (e.g. ChatGPT, Perplexity)
  • query: Group by individual query/prompt
  • date: Group by date (requires date_aggregation_interval)
  • website: Group by tracked website
Available options:
topic,
tag,
market,
model,
query,
date,
website
Examples:
["topic", "model"]

["market", "date"]
​
start_date
string<date-time>

Start of the date range (ISO 8601). Limits results to data collected on or after this date. When omitted: defaults to the latest run's start date for metric queries, or earliest available date for list queries.

Examples:

"2026-01-01T00:00:00Z"

"2026-03-01T00:00:00Z"

​
end_date
string<date-time>

End of the date range (ISO 8601). Limits results to data collected on or before this date. When omitted: defaults to today. Date-only strings (no 'T') are extended to end of day.

Examples:

"2026-01-31T23:59:59Z"

"2026-03-17T23:59:59Z"

​
order_by
SortingOrder · object[]

Sort results by one or more fields. Each entry specifies a field name and direction. Results are sorted by the first entry, then ties broken by subsequent entries.

Examples:
[
  {
    "field": "visibility_score",
    "order": "desc"
  }
]

[
  { "field": "mention_count", "order": "desc" },
  { "field": "rank", "order": "asc" }
]
​
pagination
PaginationInput · object

Control result pagination. Set limit for page size and offset to skip results. Omit to return all results (use with caution on large datasets).

Examples:
{ "limit": 10, "offset": 0 }

{ "limit": 25, "offset": 50 }
​
measures
enum<string>[]

Sentiment metrics to include. If empty, all measures are returned.

Sentiment metrics to include in the report.

  • total_keyword_occurrences: Total occurrences of tracked keywords
  • total_positive_keyword_occurrences: Occurrences of positive sentiment keywords
  • unique_positive_keywords: Count of distinct positive keywords found
  • total_unique_keywords: Count of all distinct keywords found
  • positive_subtheme_count: Count of subthemes classified as positive (majority-vote: positive keyword hits >= negative hits)
  • negative_subtheme_count: Count of subthemes classified as negative (majority-vote: negative keyword hits > positive hits)
Available options:
total_keyword_occurrences,
total_positive_keyword_occurrences,
unique_positive_keywords,
total_unique_keywords,
positive_subtheme_count,
negative_subtheme_count
Example:
[
  "total_keyword_occurrences",
  "unique_positive_keywords"
]
​
filters
SentimentFiltersInput · object

Narrow results by topics, markets, platforms, etc. All filters are optional and combine with AND logic.

​
date_aggregation_interval
enum<string>

Required when using 'date' dimension. Groups time-series data into day, week, or month buckets for trend analysis.

Available options:
day,
week,
month
Examples:

"week"

"day"

​
website_type
enum<string>

Scope results by website ownership. 'SELF' = your brand only, 'SELF+COMPETITORS' = your brand plus competitors, 'ALL' = all citations without domain filtering.

Available options:
SELF,
SELF+COMPETITORS,
ALL
Example:

"SELF"

Response

Successful Response

Response containing sentiment report data.

​
info
ResponseInfo · object

Information of the API request including total count and query details

​
data
SentimentDataRow · object[]

Array of sentiment data rows grouped by the requested dimensions