Skip to main content
GET
Sample Prompts

Overview

This endpoint samples prompts from the total prompt pool (business + products) for an organization. It’s used by the cron job to check a subset of prompts each day instead of all prompts (cost optimization). Sampling Algorithm:
  1. First, select prompts that have never been tested (last_tested_at IS NULL)
  2. If we need more to reach sample_size, randomly select from already-tested prompts
This ensures all prompts eventually get tested while prioritizing new ones.
This is an internal API used by the Cron service. Requires API key authentication.

Query Parameters

string
required
Organization slug (clerk_org_id)
integer
default:"10"
Number of prompts to sample

Response

string
"success" or "error"
string
The organization slug
integer
Total number of prompts available for this organization
integer
Number of prompts that have never been tested
integer
Actual number of prompts sampled (may be less than requested if fewer prompts exist)
array
Array of sampled prompts with metadata:
  • id: Prompt ID (integer)
  • prompt: The prompt text (string)
  • entity_id: Entity UUID (string)
  • entity_name: Entity name (string)
  • entity_type: "business" or "product" (string)

Example Response

Use Case

The visibility cron job calls this endpoint once per customer per day:
  1. Sample 10 prompts (prioritizing untested ones)
  2. Analyze each prompt across 8 AI platforms (pass/fail)
  3. Update entity_prompts_tracker with results and last_tested_at
  4. Store daily report in visibility_reports table
This approach:
  • Reduces API costs by ~50% compared to checking all prompts daily
  • Ensures all prompts eventually get tested
  • Prioritizes new prompts so users see results quickly after onboarding