Agentic Platform
Documentation API reference Tools Skills

Tools

Share Of Voice Analysis

share_of_voice_analysis Competitive analysis

Analyze the share of voice (no brand config required)

Analyze the share of voice with per-brand sentiment and addressed topics

Playground

Your organization, project and token stay in this browser's local storage and are sent straight to the API — this page never sees them.

POST
item
query required The search query to analyze
text required The text to analyze
links required The links to analyze
provider_name required The provider name
config
domains required The brand's domains
llm_model Override LLM model (provider:model_name)

Billing

Fixed cost per item requested, plus one model call that reads the answers and scores the brands in them. The cost follows how many answers the item carries and how long they are. Naming another model in llm_model changes the per-token rates.

These usage SKUs can be charged on a call.

SKU Credits Description
Tool call 1 per request Charged once per successful item, on top of any usage below.
Gemini 3.1 Flash Lite (flex), input 125 per million tokens Tokens the model reads from the prompt you send.
Gemini 3.1 Flash Lite (flex), output 750 per million tokens Tokens the model writes in its answer.
Gemini 3.1 Flash Lite (flex), read from cache 12.5 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.
Gemini 3.1 Flash Lite (standard), input 250 per million tokens Tokens the model reads from the prompt you send.
Gemini 3.1 Flash Lite (standard), output 1,500 per million tokens Tokens the model writes in its answer.
Gemini 3.1 Flash Lite (standard), read from cache 25 per million tokens Tokens the model reads from a cached prompt. Cheaper than a fresh read.

Schemas

item is what you send, config how the tool behaves, and the response is what you get back.

Item

object
Properties
query string required

The search query to analyze

text string required

The text to analyze

links array required

The links to analyze

Items: Link

provider_name string required

The provider name

Example
{
  "query": "string",
  "text": "string",
  "links": [
    {
      "url": "string",
      "position": null,
      "title": null,
      "text": null
    }
  ],
  "provider_name": "string"
}

Type Definitions

1 type

These are the available sub-object types that can be used in the properties above.

Configuration

object
Properties
domains array required

The brand's domains

llm_model string

Override LLM model (provider:model_name)

Default: "google:gemini-3.1-flash-lite"

Example
{
  "domains": [
    "string"
  ],
  "llm_model": "google:gemini-3.1-flash-lite"
}

Response

object
Properties
summary string required

Summary of brand mentions and analysis

all_brands_with_sentiment array required

List of brands mentioned with their sentiment, rationale, and topics

Items: BrandMention

domain_analysis DomainsAnalysis required

Domain analysis

Type: DomainsAnalysis

Example
{
  "summary": "string",
  "all_brands_with_sentiment": [
    {
      "name": "string",
      "rationale": "string",
      "addressed_topics": []
    }
  ],
  "domain_analysis": {
    "domains_citations": [
      {
        "domain": "string",
        "best_position": 0
      }
    ],
    "best_position": 0,
    "best_position_url": "string",
    "nb_urls_matching_domain": 0
  }
}

Type Definitions

4 types

These are the available sub-object types that can be used in the properties above.

AddressedTopic object
#

A topic addressed about a brand with its sentiment.

topic string required

Topic addressed (1-3 words, e.g. 'pricing', 'reliability')

sentiment string required

Sentiment for this topic about this brand (positive, negative, or neutral)

Values: positive negative neutral

BrandMention object
#

A brand mentioned in the AI answer with rationale and per-topic sentiments.

name string required

Brand name (lowercase, no duplicates, max 100 characters)

max length 100

rationale string required

Concise explanation (1 sentence) of where/how the brand appears in the answer. Example: "Recommended as budget option in the comparison section." Example: "Listed among alternatives without detailed evaluation." Example: "Mentioned as market leader in the introduction."

addressed_topics array

Topics discussed about THIS BRAND with their sentiment (max 3). Each topic should be 1-3 words (e.g. "pricing", "reliability", "customer support"). Example for Nike: [{"topic": "durability", "sentiment": "positive"}, {"topic": "pricing", "sentiment": "negative"}, {"topic": "delivery", "sentiment": "neutral"}]

Items: AddressedTopic

Default: []

max items 3

DomainCitation object
#
domain string required
best_position integer required
DomainsAnalysis object
#
domains_citations array required

Items: DomainCitation

best_position integer | null required
best_position_url string | null required
nb_urls_matching_domain integer required

Endpoints

POST http://agents.botify.com/{organization}/{project}/share_of_voice_analysis/process
POST http://agents.botify.com/{organization}/{project}/share_of_voice_analysis/batch_process
POST http://agents.botify.com/{organization}/{project}/share_of_voice_analysis/async_process
POST http://agents.botify.com/{organization}/{project}/share_of_voice_analysis/async_batch_process

See running a long job in the background for the polling flow.

cURL

curl -X POST "http://agents.botify.com/{organization}/{project}/share_of_voice_analysis/process" \
  -H "Authorization: Bearer $BOTIFY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "item": {
    "query": "<query>",
    "text": "<text>",
    "links": [],
    "provider_name": "<provider_name>"
  },
  "config": {
    "domains": []
  }
}'

Raw metadata