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

# Overview

> Architecture for the Sample Prompts endpoint

## Purpose

Samples prompts for daily visibility checking, prioritizing prompts that have never been tested.

## Architecture

```mermaid theme={null}
flowchart TD
    Request["GET /api/cron/sample-prompts?org_slug=..."]
    
    subgraph logic [Sampling Logic]
        GetEntities["Get entities for org"]
        GetPrompts["Get all prompts"]
        SeparateUntested["Separate untested"]
        PrioritizeUntested["Prioritize untested"]
        FillWithTested["Fill with tested"]
    end
    
    subgraph db [Database]
        Entities["entities table"]
        Prompts["entity_prompts_tracker"]
    end
    
    Request --> GetEntities
    GetEntities --> Entities
    Entities --> GetPrompts
    GetPrompts --> Prompts
    Prompts --> SeparateUntested
    SeparateUntested --> PrioritizeUntested
    PrioritizeUntested --> FillWithTested
    FillWithTested --> Response
```

## Query Parameters

| Parameter     | Type     | Default  | Description                 |
| ------------- | -------- | -------- | --------------------------- |
| `org_slug`    | `string` | required | Organization identifier     |
| `sample_size` | `int`    | 10       | Number of prompts to sample |

## Sampling Algorithm

1. **Get all prompts** for the organization
2. **Separate** into untested (`last_tested_at IS NULL`) and tested
3. **Prioritize untested** - take as many as possible up to sample\_size
4. **Fill remaining** with random tested prompts

This ensures all prompts eventually get tested while prioritizing new ones.

## Response Format

```json theme={null}
{
  "status": "success",
  "org_slug": "org-slug-123",
  "total_prompts": 50,
  "untested_count": 15,
  "sample_size": 10,
  "prompts": [
    {
      "id": 123,
      "prompt": "best payment gateway for startups",
      "entity_id": "uuid-...",
      "entity_name": "Acme Corp",
      "entity_type": "business"
    }
  ]
}
```

## Code Location

```
src/app/apis/cron/sample_prompts/routes.py
```

## Used By

Daily cron job that:

1. Samples prompts with this endpoint
2. Runs visibility analysis on each
3. Updates `last_tested_at` timestamp