Get Keywords

Browse keywords that AI models associate with your brand, organized by theme and subtheme.

Example: “Which keywords does ChatGPT use when discussing our brand?”

Metrics (optional): website_count, subtheme_count, theme_count

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, theme, subtheme, websites, brand_name, keyword.

Sort fields: Any metric name, plus keyword, theme, subtheme.

Dates: If metrics are requested without dates, defaults to latest run date range. If no metrics and no dates, defaults to all-time.

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 /v2/geo/business/keywords

Get Keywords

cURL

curl --request POST \
  --url https://api.writesonic.com/v2/geo/business/keywords \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "project_id": "<string>",
  "start_date": "2023-11-07T05:31:56Z",
  "end_date": "2023-11-07T05:31:56Z",
  "order_by": [
    {
      "field": "<string>"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "metrics": [],
  "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>"
        }
      ]
    },
    "advanced_filters": {
      "join": "and",
      "conditions": [
        {
          "operator": "<string>",
          "value": "<unknown>"
        }
      ]
    },
    "theme": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "subtheme": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "websites": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "brand_name": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    },
    "keyword": {
      "condition": "AND",
      "items": [
        {
          "value": "<unknown>"
        }
      ]
    }
  }
}
'

200

{
  "data": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "keyword": "<string>",
      "brand_name": "<string>",
      "website": "<string>",
      "subtheme": "<string>",
      "theme": "<string>",
      "created_date": "2023-12-25",
      "website_count": 123,
      "subtheme_count": 123,
      "theme_count": 123
    }
  ],
  "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": {}
    }
  }
}

Authorizations

X-API-KEY · string · header · required

Body

application/json

Request parameters for retrieving all keywords.

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"

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 }

metrics · enum<string>[]

Metrics to include. Options: website_count, subtheme_count, theme_count.

Available options: website_count, subtheme_count, theme_count

Example:

["website_count"]

filters · KeywordFiltersInput · object

Optional filters by theme, subtheme, website, brand, or keyword.

Show child attributes

Response

200

application/json

Successful Response

Response containing keyword report data.

data · KeywordDataItem · object[] · required

Array of keyword data items

Show child attributes

info · ResponseInfo · object

Information of the API request including total count and query details

Show child attributes