> ## Documentation Index
> Fetch the complete documentation index at: https://docs.searchcompany.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sample Prompts

> Sample prompts for daily visibility check, prioritizing untested 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.

<Warning>
  This is an internal API used by the Cron service. Requires API key authentication.
</Warning>

## Query Parameters

<ParamField query="org_slug" type="string" required>
  Organization slug (clerk\_org\_id)
</ParamField>

<ParamField query="sample_size" type="integer" default="10">
  Number of prompts to sample
</ParamField>

## Response

<ResponseField name="status" type="string">
  `"success"` or `"error"`
</ResponseField>

<ResponseField name="org_slug" type="string">
  The organization slug
</ResponseField>

<ResponseField name="total_prompts" type="integer">
  Total number of prompts available for this organization
</ResponseField>

<ResponseField name="untested_count" type="integer">
  Number of prompts that have never been tested
</ResponseField>

<ResponseField name="sample_size" type="integer">
  Actual number of prompts sampled (may be less than requested if fewer prompts exist)
</ResponseField>

<ResponseField name="prompts" type="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)
</ResponseField>

## Example Response

```json theme={null}
{
  "status": "success",
  "org_slug": "acme-corp",
  "total_prompts": 150,
  "untested_count": 45,
  "sample_size": 10,
  "prompts": [
    {
      "id": 42,
      "prompt": "best project management software for small teams",
      "entity_id": "550e8400-e29b-41d4-a716-446655440000",
      "entity_name": "Acme Corp",
      "entity_type": "business"
    },
    {
      "id": 87,
      "prompt": "acme widget pro vs competitor",
      "entity_id": "550e8400-e29b-41d4-a716-446655440001",
      "entity_name": "Widget Pro",
      "entity_type": "product"
    }
  ]
}
```

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