Get Performance Report

curl --request POST \
  --url https://api.writesonic.com/v2/geo/reports/performance \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "project_id": "<string>",
  "dimensions": [],
  "start_date": "2023-11-07T05:31:56Z",
  "end_date": "2023-11-07T05:31:56Z",
  "order_by": [
    {
      "field": "<string>"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "measures": [],
  "filters": {
    "topics": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "prompts": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "tags": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "markets": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "intent": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "branded": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "platform": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "has_shopping_card": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "has_ads_data": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "visibility": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "rank": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "website_mentioned_in_answer": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "cited_page_url": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "cited_domain": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "website_mentioned_in_citation": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "status": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    }
  }
}
'

{
  "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>",
      "share_of_voice": 123,
      "citation_share": 123,
      "mention_count": 123,
      "visibility_score": 123,
      "citation_count": 123,
      "rank": 123,
      "citing_answers": 123,
      "number_of_answers": 123,
      "sentiment_positive": 123,
      "sentiment_negative": 123
    }
  ]
}

Reports

Get Performance Report

Brand performance metrics grouped by one or more dimensions.

Example: “Show me visibility score by model, broken down by week.”

Dimensions (at least 1 required): topic, tag, market, model, query, date, website

date supports optional date_aggregation_interval: day (default) | week | month
website auto-sets website_type to SELF+COMPETITORS (default is SELF)

Measures (omit for all): share_of_voice, citation_share, visibility_score, mention_count, citation_count, rank, citing_answers, number_of_answers, sentiment

Filters: topics, prompts, tags, markets, intent, branded, platform, has_shopping_card, visibility, rank, website_mentioned_in_answer, cited_page_url, cited_domain, website_mentioned_in_citation, status.

Sort fields: Any measure name, plus date, query_name, topic_name, market_name, model_name, website_name, tag_name.

Dates: If no dates provided, defaults to latest run date range. Provide start_date and end_date in ISO 8601 format to specify a custom range.

Pagination: Use pagination (limit 1-100, default 10; offset for paging). Use order_by for sorting.

Response: Returns data array with info metadata containing total_rows (before pagination) and query (applied metrics, dates, sorting, pagination, filters).

POST

geo

reports

performance

Get Performance Report

curl --request POST \
  --url https://api.writesonic.com/v2/geo/reports/performance \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "project_id": "<string>",
  "dimensions": [],
  "start_date": "2023-11-07T05:31:56Z",
  "end_date": "2023-11-07T05:31:56Z",
  "order_by": [
    {
      "field": "<string>"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "measures": [],
  "filters": {
    "topics": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "prompts": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "tags": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "markets": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "intent": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "branded": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "platform": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "has_shopping_card": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "has_ads_data": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "visibility": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "rank": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "website_mentioned_in_answer": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "cited_page_url": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "cited_domain": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "website_mentioned_in_citation": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "status": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    }
  }
}
'

{
  "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>",
      "share_of_voice": 123,
      "citation_share": 123,
      "mention_count": 123,
      "visibility_score": 123,
      "citation_count": 123,
      "rank": 123,
      "citing_answers": 123,
      "number_of_answers": 123,
      "sentiment_positive": 123,
      "sentiment_negative": 123
    }
  ]
}

Authorizations

X-API-KEY

string

header

required

Body

application/json

Request parameters for the Performance Report API.

project_id

string

required

Unique identifier of the project to query. Get valid project IDs from get_all_projects.

Minimum string length: 1

Example:

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

dimensions

enum<string>[]

required

Dimensions to group results 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
shopping: Group by whether the response has a shopping card (true/false)
ads: Group by whether the response has sponsored/ad placements (true/false)
branded: Group by whether the underlying query is branded (true/false)

Available options:

topic,

tag,

market,

model,

query,

date,

website,

shopping,

ads,

branded

Examples:

["model", "market"]

["topic", "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.

Show child attributes

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).

Show child attributes

Examples:

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

{ "limit": 25, "offset": 50 }

measures

enum<string>[]

Performance metrics to include in the response. If empty, all measures are returned.

Performance metrics to include in the report.

share_of_voice: Percentage of AI responses mentioning the brand (0-100)
citation_share: Percentage of citations attributed to the brand (0-100)
mention_count: Total number of mentions in AI responses
visibility_score: Calculated visibility score based on rank and frequency
citation_count: Total number of citations received
rank: Average rank position in AI responses (lower is better)
citing_answers: Number of AI answers that include citations
number_of_answers: Total number of AI answers analyzed
sentiment: Returns sentiment_positive (0-100%) and sentiment_negative (0-100%) showing keyword sentiment breakdown

Available options:

share_of_voice,

citation_share,

mention_count,

visibility_score,

citation_count,

rank,

citing_answers,

number_of_answers,

sentiment

Example:

["share_of_voice", "visibility_score"]

filters

PerformanceFiltersInput · object

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

Show child attributes

date_aggregation_interval

enum<string>

Optional. When using the 'date' dimension, controls time-series bucket size. Defaults to 'day' if omitted. Options: day, week, month.

Available options:

day,

week,

month

Examples:

"week"

"month"

website_type

enum<string>

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

Available options:

SELF,

SELF+COMPETITORS,

ALL

Examples:

"SELF"

"SELF+COMPETITORS"

"ALL"

Response

Successful Response

Response containing performance report data.

info

ResponseInfo · object

Information of the API request including total count and query details

Show child attributes

data

PerformanceDataRow · object[]

Array of performance data rows grouped by the requested dimensions

Show child attributes

Get All Projects

Get Citation Report

⌘I