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

# Search Insights

> POST /api/insights/search, semantic search over the Alchemist database.

## `POST /api/insights/search`

Searches the Alchemist database and returns ranked insights. Each insight includes the verbatim source excerpt it was derived from, the originating document, and relevance score.

Insights are embedded with **HyDE**, the index stores both the insight text and hypothetical questions it can answer. This makes focused keyword phrases and concise questions work well as queries.

### Authentication

`X-API-Key: alch_YOUR_KEY`

### Request body

```json theme={null}
{
  "query": "Fed dot plot rate path 2026",
  "source_name": "SEC",
  "since": "2026-01-01",
  "limit": 20
}
```

| Field | Type | Required | Description |
| - | - | - | - |
| `query` | `string` | Yes | One focused concept, a concise question or 3–8 keyword phrase. Avoid conversational wrappers and multi-theme queries. |
| `source_name` | `string \| null` | No | Partial, case-insensitive match on publishing organization. Use `GET /api/documents/filters` to see valid values. |
| `since` | `string (date)` | No | ISO 8601 date (`YYYY-MM-DD`). Only returns insights from documents published on or after this date. |
| `limit` | `integer` | No | Max insights to return. Default `20`. |

### Response `200`

```json theme={null}
{
  "insights": [
    {
      "insight_id": "ins_01jwx9z3kq7f4vbr",
      "title": "Grasberg Block Cave ramp-up delayed by ore loading modifications",
      "insight": "PTFI commenced phased ramp-up of Grasberg Block Cave Production Blocks 2 and 3 in March 2026 but encountered a significant increase in wet drawpoints, limiting near-term production to approximately 60% of capacity. 2026 sales estimates were reduced from 3.4 billion to 3.1 billion pounds of copper.",
      "excerpts": [
        "During initial ramp-up activities in Production Blocks 2 and 3, PTFI encountered changes in operating conditions at the Grasberg Block Cave underground mine, resulting in a significant increase in the ratio of wet drawpoints."
      ],
      "doc_id": "doc_01jww8y2hp6e3uaq",
      "doc_title": "Freeport Reports First-Quarter 2026 Results",
      "source_url": "https://www.sec.gov/Archives/edgar/data/831259/000083125926000021/a1q2026exhibit991.htm",
      "source_name": "SEC",
      "published_date": "2026-04-23",
      "score": 0.92
    }
  ]
}
```

| Field | Type | Description |
| - | - | - |
| `insight_id` | `string` | Unique insight identifier |
| `title` | `string` | Short title for the insight |
| `insight` | `string` | The extracted finding, written as a complete statement |
| `excerpts` | `string[]` | Verbatim quotes from the source document that support the insight |
| `doc_id` | `string` | Parent document ID, use with `GET /api/documents/{doc_id}` |
| `doc_title` | `string` | Title of the originating document |
| `source_url` | `string` | Direct URL to the primary source |
| `source_name` | `string` | Publishing organization |
| `published_date` | `string \| null` | Publication date of the source document |
| `score` | `float` | Semantic relevance score (0–1). Higher is more relevant. |

### Query writing guide

<AccordionGroup>
  <Accordion title="Good query patterns">
    | Pattern | Example |
    | - | - |
    | Concise question | `"What did Freeport say about copper production guidance?"` |
    | Entity + metric | `"AAPL 2025 revenue guidance"` |
    | Theme + source keyword | `"copper production guidance SEC"` |
    | Policy + date | `"Fed dot plot March 2026"` |
    | Sector + event | `"natural gas inventory EIA weekly"` |
  </Accordion>

  <Accordion title="Patterns to avoid">
    | Anti-pattern | Why |
    | - | - |
    | `"Tell me about the latest Fed meeting"` | Conversational wrapper adds noise |
    | `"Fed rates inflation corn energy stocks bonds"` | Multi-theme keyword soup dilutes the embedding |
    | `"What does Wall Street think?"` | Too vague, no entity to anchor the search |
  </Accordion>

  <Accordion title="Refining a sparse result">
    If `search_insights` returns 0 or very few results:

    1. Try a more specific phrasing: `"Q4 2025 guidance"` → `"Q4 2025 revenue outlook earnings call"`
    2. Remove filters (`source_name`, `since`) and try again
    3. Try an alternative entity name or acronym: `"Bureau of Labor Statistics"` → `"BLS"`
    4. Call `GET /api/documents/filters` to confirm the source name you're filtering on is in the database
  </Accordion>
</AccordionGroup>

### Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.askalchemist.com/api/insights/search \
    -H "X-API-Key: alch_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "copper production guidance",
      "source_name": "SEC",
      "since": "2026-01-01"
    }'
  ```

  ```python Python (httpx) theme={null}
  import httpx

  resp = httpx.post(
      "https://api.askalchemist.com/api/insights/search",
      headers={"X-API-Key": "alch_YOUR_KEY"},
      json={
          "query": "copper production guidance",
          "source_name": "SEC",
          "since": "2026-01-01",
      },
  )
  data = resp.json()
  for i in data["insights"]:
      print(f"[{i['score']:.2f}] {i['title']}")
      print(f"  {i['insight']}")
      print(f"  Source: {i['source_name']} ({i['published_date']})")
      print()
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch("https://api.askalchemist.com/api/insights/search", {
    method: "POST",
    headers: {
      "X-API-Key": "alch_YOUR_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: "copper production guidance",
      source_name: "SEC",
      since: "2026-01-01",
    }),
  });

  const { insights } = await res.json();
  ```
</CodeGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.