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

# Deep Research

> Multi-step research for comprehensive analysis

We automatically search, analyze, and synthesize information into a detailed report.

```bash title="Endpoint" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST /search/v1/research
```

<CodeGroup>
  ```bash title="cURL" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  curl -X POST https://api.case.dev/search/v1/research \
    -H "Authorization: Bearer sk_case_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "instructions": "Research HIPAA enforcement actions in 2024",
      "model": "pro"
    }'
  ```

  ```bash title="CLI" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  casedev search:v1 research \
    --instructions "Research topic..." \
    --model pro
  ```

  ```typescript title="Typescript" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  import Casedev from 'casedev';

  const client = new Casedev({ apiKey: 'sk_case_YOUR_API_KEY' });

  // Start research
  const research = await client.search.v1.research({
    instructions: 'Research HIPAA enforcement actions in 2024, focusing on healthcare data breaches and penalties.',
    model: 'pro'
  });

  console.log(research.researchId);  // Poll this for results
  ```

  ```python title="Python" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  import casedev

  client = casedev.Casedev(api_key='sk_case_YOUR_API_KEY')

  # Start research
  research = client.search.v1.research(
      instructions='Research HIPAA enforcement actions in 2024, focusing on healthcare data breaches and penalties.',
      model='pro'
  )

  print(research.research_id)  # Poll this for results
  ```

  ```go title="Go" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  research, _ := client.Search.V1.Research(ctx, casedev.SearchV1ResearchParams{
  	Instructions: casedev.F("Research topic..."),
  	Model:        casedev.F("pro"),
  })
  fmt.Println(research.ResearchID)
  ```
</CodeGroup>

```json title="Response" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "researchId": "res_abc123xyz",
  "status": "processing",
  "model": "pro"
}
```

## Get results

<CodeGroup>
  ```bash title="cURL" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  curl https://api.case.dev/search/v1/research/res_abc123xyz \
    -H "Authorization: Bearer sk_case_YOUR_API_KEY"
  ```

  ```bash title="CLI" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  casedev search:v1 retrieve-research --id $RESEARCH_ID
  ```

  ```typescript title="Typescript" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  // Poll for results
  let result = await client.search.v1.retrieveResearch(researchId);

  while (result.status !== 'completed') {
    await new Promise(r => setTimeout(r, 5000));
    result = await client.search.v1.retrieveResearch(researchId);
  }

  console.log(result.report);  // Full research report in Markdown
  console.log(result.sources); // Sources used
  ```

  ```python title="Python" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  import time

  # Poll for results
  result = client.search.v1.retrieve_research(research_id)

  while result.status != 'completed':
      time.sleep(5)
      result = client.search.v1.retrieve_research(research_id)

  print(result.report)   # Full research report in Markdown
  print(result.sources)  # Sources used
  ```

  ```go title="Go" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  result, _ := client.Search.V1.GetResearch(ctx, researchID, casedev.SearchV1GetResearchParams{})
  fmt.Println(result.Status)
  fmt.Println(result.Report)
  ```
</CodeGroup>

```json title="Response" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "researchId": "res_abc123xyz",
  "status": "completed",
  "report": "## HIPAA Enforcement in 2024\n\n### Overview\nThe Office for Civil Rights (OCR) has significantly increased enforcement...\n\n### Key Findings\n1. **Increased Penalties**: Average penalties rose 45%...\n\n### Notable Cases\n- **Healthcare Provider X**: $2.3M penalty for...",
  "sources": [
    {
      "url": "https://hhs.gov/hipaa/enforcement-2024",
      "title": "OCR Enforcement Actions 2024"
    }
  ],
  "metadata": {
    "searchesPerformed": 12,
    "sourcesAnalyzed": 47,
    "processingTimeMs": 45000
  }
}
```

## Parameters

| Parameter      | Type   | Default      | Description                       |
| -------------- | ------ | ------------ | --------------------------------- |
| `instructions` | string | **Required** | Research question/instructions    |
| `model`        | string | `normal`     | Research depth (see below)        |
| `outputSchema` | object | —            | JSON schema for structured output |

### Research models

| Model    | Depth | Speed    | Use case               |
| -------- | ----- | -------- | ---------------------- |
| `fast`   | Basic | \~30 sec | Quick fact-checking    |
| `normal` | Good  | \~2 min  | Standard research      |
| `pro`    | Best  | \~5 min  | Complex legal research |

## Examples

### Legal research

<CodeGroup>
  ```bash title="CLI" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  casedev search:v1 research \
    --instructions "Research recent developments in non-compete agreement enforceability across US states, focusing on 2024 legislation and court decisions." \
    --model pro
  ```

  ```typescript title="Typescript" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  const research = await client.search.v1.research({
    instructions: 'Research recent developments in non-compete agreement enforceability across US states, focusing on 2024 legislation and court decisions.',
    model: 'pro'
  });
  ```

  ```python title="Python" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  research = client.search.v1.research(
      instructions='Research recent developments in non-compete agreement enforceability across US states, focusing on 2024 legislation and court decisions.',
      model='pro'
  )
  ```

  ```go title="Go" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  research, _ := client.Search.V1.Research(ctx, casedev.SearchV1ResearchParams{
      Instructions: casedev.F("Research recent developments in non-compete agreement enforceability across US states, focusing on 2024 legislation and court decisions."),
      Model:        casedev.F(casedev.SearchV1ResearchParamsModelPro),
  })
  ```
</CodeGroup>

### Due diligence

<CodeGroup>
  ```bash title="CLI" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  casedev search:v1 research \
    --instructions "Research Acme Corporation litigation history over the past 5 years, including settlements, verdicts, and ongoing cases." \
    --model pro
  ```

  ```typescript title="Typescript" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  const research = await client.search.v1.research({
    instructions: 'Research Acme Corporation litigation history over the past 5 years, including settlements, verdicts, and ongoing cases.',
    model: 'pro'
  });
  ```

  ```python title="Python" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  research = client.search.v1.research(
      instructions='Research Acme Corporation litigation history over the past 5 years, including settlements, verdicts, and ongoing cases.',
      model='pro'
  )
  ```

  ```go title="Go" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  research, _ := client.Search.V1.Research(ctx, casedev.SearchV1ResearchParams{
      Instructions: casedev.F("Research Acme Corporation litigation history over the past 5 years, including settlements, verdicts, and ongoing cases."),
      Model:        casedev.F(casedev.SearchV1ResearchParamsModelPro),
  })
  ```
</CodeGroup>

### Structured output

<CodeGroup>
  ```bash title="CLI" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  casedev search:v1 research \
    --instructions "Research the top 5 law firms specializing in patent litigation" \
    --model normal
  ```

  ```typescript title="Typescript" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  const research = await client.search.v1.research({
    instructions: 'Research the top 5 law firms specializing in patent litigation',
    model: 'normal',
    outputSchema: {
      type: 'object',
      properties: {
        firms: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              name: { type: 'string' },
              headquarters: { type: 'string' },
              notableCases: { type: 'array', items: { type: 'string' } }
            }
          }
        }
      }
    }
  });
  ```

  ```python title="Python" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  research = client.search.v1.research(
      instructions='Research the top 5 law firms specializing in patent litigation',
      model='normal',
      output_schema={
          'type': 'object',
          'properties': {
              'firms': {
                  'type': 'array',
                  'items': {
                      'type': 'object',
                      'properties': {
                          'name': {'type': 'string'},
                          'headquarters': {'type': 'string'},
                          'notableCases': {'type': 'array', 'items': {'type': 'string'}}
                      }
                  }
              }
          }
      }
  )
  ```

  ```go title="Go" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  research, _ := client.Search.V1.Research(ctx, casedev.SearchV1ResearchParams{
      Instructions: casedev.F("Research the top 5 law firms specializing in patent litigation"),
      Model:        casedev.F(casedev.SearchV1ResearchParamsModelNormal),
  })
  ```
</CodeGroup>

<Info>
  **Tip:** Be specific in your instructions. "Research HIPAA enforcement in 2024" produces better results than "Tell me about HIPAA."
</Info>

<Warning>
  **Web data only.** For comprehensive legal research, use Lexis, Westlaw, or OpenLaws.
</Warning>