Get the latest suggestion for a campaign optimization

Retrieve the latest suggestion for a specific campaign optimization. Required permission: read:analysis.

The response format depends on the Accept header. Supported formats: JSON (default), CSV (Google Ads only), XLSX (TikTok only).

Suggestion Item Structure (Google Ads — optimization_suggestions.asset_groups.<id>[])

Each suggestion item in the array contains:

{
  "keyword": "running shoes for beginners",
  "suggestion": "add",
  "keyword_en": "running shoes for beginners",
  "relevancy_score": 85,
  "strength": "very_strong",
  "currently_used_in": 2
}

Fields:

• keyword (string): The search theme text in the campaign language.
• suggestion (string): Action — add, keep, or remove.
• keyword_en (string, optional): English translation. Only present when translate_to_en=true and language is not English.
• relevancy_score (int, 0–100): Semantic similarity between the keyword and the asset group. Computed via embedding distance.
• strength (string): Label derived from the relevancy score — very_strong (80–100), strong (60–79), average (40–59), weak (20–39), very_weak (0–19).
• currently_used_in (int, ≥1): Number of asset groups within this optimization that include the same keyword. Represents overlap across the selected asset group set, not live Google Ads usage.

Note: relevancy_score, strength, and currently_used_in are only present for Google Ads suggestions. TikTok suggestions do not include these fields.

GET /v1/organizations/{organization_id}/workspaces/{workspace_id}/campaign_optimizations/{campaign_optimization_id}/suggestions

Get the latest suggestion for a campaign optimization

cURL

curl --request GET \
  --url https://api.shareofmodel.ai/v1/organizations/{organization_id}/workspaces/{workspace_id}/campaign_optimizations/{campaign_optimization_id}/suggestions \
  --header 'Authorization: <api-key>'

200

[
  {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "suggestion": "<unknown>",
    "created_at": "2023-11-07T05:31:56Z",
    "workspace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "platform_integration_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "campaign": "<unknown>",
    "name": "<string>",
    "analysis": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
]

Authorizations

Authorization · string · header · required

Headers

Accept · string

Content type for the response. Possible values: 'application/json' (default, returns JSON with suggestion data), 'text/csv' (returns CSV file, Google Ads only), 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' (returns XLSX file, TikTok only).

Path Parameters

campaign_optimization_id · string · required

id · string<uuid> · required

A UUID string identifying the campaign optimization.

organization_id · string · required

workspace_id · string<uuid> · required

Query Parameters

format · enum<string>

Available options: csv, json, xlsx

translate_to_en · boolean · default: false

If true and campaign language is not English, translates keywords to English and adds keyword_en field. Only applies to JSON responses.

Response

200

application/json

Details of the latest suggestion. Content type depends on Accept header: JSON (application/json), CSV (text/csv, Google Ads only), or XLSX (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, TikTok only).

id · string<uuid> · required · read-only

suggestion · any · required

created_at · string<date-time> · required · read-only

workspace_id · string<uuid> · required

platform_integration_id · string<uuid> · required

platform · enum<string> · required

• google_ads - google ads
• tiktok - tiktok

Available options: google_ads, tiktok

campaign · any · required

name · string · required

Maximum string length: 255

analysis · string<uuid> · required

status · enum<string>

• pending - pending
• in_progress - in progress
• completed - completed
• failed - failed
• suggestions_applied - suggestions applied

Available options: pending, in_progress, completed, failed, suggestions_applied

language · enum<string>

• ar - ar
• da - da
• de - de
• en - en
• es - es
• eu - eu
• fi - fi
• fil - fil
• fr - fr
• he - he
• hi - hi
• hu - hu
• id - id
• it - it
• ja - ja
• ko - ko
• nl - nl
• pl - pl
• pt - pt
• ro - ro
• sv - sv
• th - th
• tr - tr
• ur - ur
• vi - vi
• zh - zh
• zh-TW - zh TW

Available options: ar, da, de, en, es, eu, fi, fil, fr, he, hi, hu, id, it, ja, ko, nl, pl, pt, ro, sv, th, tr, ur, vi, zh, zh-TW,