Campaign Optimizations

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

organizations

{organization_id}

workspaces

{workspace_id}

campaign_optimizations

{campaign_optimization_id}

suggestions

Get the latest suggestion for a campaign optimization

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>'

import requests

url = "https://api.shareofmodel.ai/v1/organizations/{organization_id}/workspaces/{workspace_id}/campaign_optimizations/{campaign_optimization_id}/suggestions"

headers = {"Authorization": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://api.shareofmodel.ai/v1/organizations/{organization_id}/workspaces/{workspace_id}/campaign_optimizations/{campaign_optimization_id}/suggestions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.shareofmodel.ai/v1/organizations/{organization_id}/workspaces/{workspace_id}/campaign_optimizations/{campaign_optimization_id}/suggestions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.shareofmodel.ai/v1/organizations/{organization_id}/workspaces/{workspace_id}/campaign_optimizations/{campaign_optimization_id}/suggestions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.shareofmodel.ai/v1/organizations/{organization_id}/workspaces/{workspace_id}/campaign_optimizations/{campaign_optimization_id}/suggestions")
  .header("Authorization", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.shareofmodel.ai/v1/organizations/{organization_id}/workspaces/{workspace_id}/campaign_optimizations/{campaign_optimization_id}/suggestions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

[
  {
    "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",
    "platform": "google_ads",
    "campaign": "<unknown>",
    "name": "<string>",
    "analysis": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "pending",
    "failure_reason": "platform_access_lost",
    "language": "ar"
  }
]

Authorizations

Authorization

string

header

required

Headers

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

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

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

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

failure_reason

enum<string> | null

platform_access_lost - platform access lost
unknown - unknown

Available options:

platform_access_lost,

unknown,

null

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
no - no
pl - pl
pt - pt
ro - ro
sv - sv
th - th
tr - tr
ur - ur
vi - vi
zh - zh
zh-TW - zh TW
zh-HK - zh HK

Available options:

ar,

da,

de,

en,

es,

eu,

fi,

fil,

fr,

he,

hi,

hu,

id,

it,

ja,

ko,

nl,

no,

pl,

pt,

ro,

sv,

th,

tr,

ur,

vi,

zh,

zh-TW,

zh-HK,

Get the latest suggestion for a campaign optimization

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>'

import requests

url = "https://api.shareofmodel.ai/v1/organizations/{organization_id}/workspaces/{workspace_id}/campaign_optimizations/{campaign_optimization_id}/suggestions"

headers = {"Authorization": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://api.shareofmodel.ai/v1/organizations/{organization_id}/workspaces/{workspace_id}/campaign_optimizations/{campaign_optimization_id}/suggestions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.shareofmodel.ai/v1/organizations/{organization_id}/workspaces/{workspace_id}/campaign_optimizations/{campaign_optimization_id}/suggestions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.shareofmodel.ai/v1/organizations/{organization_id}/workspaces/{workspace_id}/campaign_optimizations/{campaign_optimization_id}/suggestions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.shareofmodel.ai/v1/organizations/{organization_id}/workspaces/{workspace_id}/campaign_optimizations/{campaign_optimization_id}/suggestions")
  .header("Authorization", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.shareofmodel.ai/v1/organizations/{organization_id}/workspaces/{workspace_id}/campaign_optimizations/{campaign_optimization_id}/suggestions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

[
  {
    "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",
    "platform": "google_ads",
    "campaign": "<unknown>",
    "name": "<string>",
    "analysis": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "pending",
    "failure_reason": "platform_access_lost",
    "language": "ar"
  }
]

Overview

Core API

Search API

Get the latest suggestion for a campaign optimization

Authorizations

Headers

Path Parameters

Query Parameters

Response