Get Benchmark Context

Get industry benchmark context for AI-powered recommendations.

⚠️ IMPORTANT: This tool retrieves READ-ONLY data. Safe to call multiple times.

🎯 What This Tool Does (Performance Agent - Phase 1 Feature 5):

Generates contextual benchmark data for the user’s business
Combines business profile with industry benchmarks
Provides recommended ROAS targets based on vertical
Returns formatted context for AI prompts

Returns benchmark context:

Business vertical and size context
Industry-specific ROAS benchmarks (typical, good, excellent)
CTR benchmarks by industry
CPC expectations for the vertical
Seasonality considerations
Custom recommendations based on profile

Industry Benchmarks Included:

Vertical	Typical ROAS	Good ROAS	Excellent ROAS
Retail	4.0x	6.0x	8.0x
Services	3.0x	5.0x	7.0x
Technology	3.5x	5.5x	8.0x
Healthcare	2.5x	4.0x	6.0x
Finance	5.0x	8.0x	12.0x
Education	2.0x	3.5x	5.0x

Parameters:

include_recommendations: Include performance recommendations (default: true)
customer_id: Optional (uses connected account if omitted)

Use this tool when:

Before providing performance analysis
When comparing user’s metrics to industry standards
User asks “how am I doing compared to others?”
You need context for optimization recommendations

Integration with Other Tools: Call this BEFORE or AFTER these tools for enhanced recommendations:

analyze_wasted_spend - Contextualize waste against industry norms
optimize_budget_allocation - Use industry-appropriate ROAS targets
get_campaign_performance - Compare metrics to benchmarks
explain_performance_anomaly - Understand if changes are industry-wide

Execution time: 1-2 seconds (profile lookup + benchmark calculation)

POST

api

tools

get_benchmark_context

execute

Get Benchmark Context

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/get_benchmark_context/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "customer_id": "string",
    "include_recommendations": true
  }
}
'

{
  "data": {
    "quota": {
      "limit": 150,
      "period_end": "2026-05-01",
      "tier": "plus",
      "used": 42
    },
    "text": "(tool-specific textual output for get_benchmark_context)"
  },
  "success": true,
  "tool": "get_benchmark_context"
}

Authorizations

Authorization

string

header

required

API key from https://adspirer.ai/keys. Prefix sk_live_. Treat as a secret — never commit.

Headers

Idempotency-Key

string<uuid>

Client-generated UUID to make writes idempotent. Strongly recommended for write tools. A repeat call with the same key returns the cached result instead of re-executing. Example: 550e8400-e29b-41d4-a716-446655440000

Body

application/json

All tool arguments are wrapped in an arguments object. The fields accepted inside arguments are listed below — required fields are marked with a red asterisk.

arguments

object

required

Input schema for getting benchmark context for AI prompts

Show child attributes

Response

Tool executed successfully. data.text carries the human-readable result (markdown-friendly). data.quota shows your current usage against the plan limit. data.structured appears when the tool emits machine-parseable structured content. data.content appears for tools that return non-text blocks (images, resources).

Returned on HTTP 200. data.text is the primary human-readable output. data.quota is always present for billable calls. data.structured is set only when the tool emits machine-parseable structured content. data.content is set only when the tool emits non-text content blocks.

data

object

required

Show child attributes

success

boolean

required

tool

string

required

Echoed tool_name from the request URL.

Last modified on April 23, 2026

Get Business ProfileGet the user's business profile for contextual recommendations. ⚠️ IMPORTANT: This tool retrieves READ-ONLY data. Safe to call multiple times. 🎯 **What This Tool Does (Performance Agent - Phase 1 Feature 5):** - Retrieves the user's saved business profile - Returns business vertical, size, goals, target audience - Provides context for more relevant recommendations - Shows profile source (user-set, inferred, or none) **Returns business context:** - Business vertical (retail, services, technology, etc.) - Business size (small, medium, large) - Primary goal (leads, sales, awareness, traffic) - Target audience description - Geographic focus (local, regional, national, international) - Seasonality patterns - Profile confidence level **Use this tool when:** - You need business context for recommendations - Before providing industry-specific advice - User asks "what type of business am I?" - You want to personalize optimization suggestions **If no profile exists:** - Use `infer_business_profile` to automatically detect from campaign data - Or ask user to provide business details via `save_business_profile` **Execution time:** 1-2 seconds (database lookup)

Get Benchmark Context

curl --request POST \
  --url https://api.adspirer.ai/api/v1/tools/get_benchmark_context/execute \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "arguments": {
    "customer_id": "string",
    "include_recommendations": true
  }
}
'

{
  "data": {
    "quota": {
      "limit": 150,
      "period_end": "2026-05-01",
      "tier": "plus",
      "used": 42
    },
    "text": "(tool-specific textual output for get_benchmark_context)"
  },
  "success": true,
  "tool": "get_benchmark_context"
}