Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.get-spotlight.com/llms.txt

Use this file to discover all available pages before exploring further.

These guidelines help AI assistants use Spotlight MCP safely and effectively. Agents can also call get_spotlight_usage_guide at runtime to retrieve this guidance as Markdown.
  1. get_organization_context — once per session; confirms auth and plan scope.
  2. list_brands — pick which brand(s) to work with.
  3. get_brand_context — before any prompt edits or limit-sensitive operations.
  4. get_spotlight_usage_guide — when writing or restructuring prompts.

​
Regular analysis prompts

Regular prompts power your weekly AI visibility reports. Write them like real search queries:
  • Neutral and unbranded — do not include the client’s brand name in the prompt text.
  • Consideration-stage when appropriate — comparison, evaluation, migration, pricing models, and “how to choose” intents reflect discovery behavior.
  • Topic-organized — every prompt belongs to a topic. Use batch_create_topics_and_prompts for bulk setup.

​
Quota awareness

get_brand_context returns promptQuota.remainingSlots. Never create more prompts than remaining slots allow. If the quota is exhausted, delete unused prompts with delete_prompts before adding new ones.

​
Bulk deletes

When removing multiple prompts, use delete_prompts with all IDs in one call. Do not call delete_prompt repeatedly — it is slower and wastes rate limit quota.

​
Perception prompts

Perception prompts are branded — they evaluate how the brand is perceived on specific properties (trust, clarity, etc.).
  • Use add_perception_prompts to create them.
  • Include scoringLogic (or goodScore / badScore) when scores need to be interpretable.
  • Read results with get_brand_perception_prompts_responses or get_run_perception_prompts_responses.
Custom perception prompts must be enabled on your plan.

​
Scheduled data collection

Prompt and topic changes do not trigger an immediate analysis run. New and updated prompts are picked up on the next scheduled report. After write operations, tools may return:
  • nextScheduledRunAt — estimated time of the next run
  • schedulingNote — explains that timing is approximate
nextEstimatedScheduledFetchAt from get_brand_context is derived from schedule frequency and last activity. Actual cron timing may differ slightly.

​
Reading analysis data

GoalSuggested tools
Latest snapshotget_brand_last_results, get_run_stats on latest run ID from list_brand_runs
Historical comparisonlist_brand_runs then get_run_stats per run
Citations and sourcesget_run_sources
Content backlog ideasget_run_content_suggestions
Full LLM answersget_run_results with includeAnswer: true (large payloads)
Prefer get_run_stats for dashboards and summaries — it returns pre-aggregated metrics including topic breakdown and top mentioned brands.

​
Scope and permissions

  • One API key = one organization. You cannot access other orgs’ data.
  • User role restrictions apply: viewer and guest accounts are read-only and cannot use write tools.
  • Rate limit defaults to 120 requests per minute per organization.

​
Example agent prompts

These are natural-language instructions you can give a connected assistant: 
List all brands in my Spotlight organization and show how many prompts each has.

For brand BRAND_ID, summarize the latest run stats and top 5 mentioned competitors.

Add a topic called "Enterprise security" with three neutral comparison prompts.
Check remaining prompt slots first.

Export all perception prompt responses from the latest run for brand BRAND_ID.

Connect an MCP client

Cursor, Claude Desktop, and generic HTTP setup.

Tools reference

Full tool list with parameters.

Authentication

API keys and rate limits.

Errors

HTTP status codes and troubleshooting.