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

# Collections

> Create reusable source bundles for your searches

Collections let you save groups of sources and reference them by name in API calls. Instead of listing multiple sources every time, create a collection once and reuse it across all your searches.

<Note>
  Collections are in **beta**. Create and manage them at [platform.valyu.ai/user/collections](https://platform.valyu.ai/user/collections).
</Note>

## What You Can Do

* **Save source combinations** - Bundle frequently-used domains and datasets
* **Simplify API calls** - Reference multiple sources with a single name
* **Share with your team** - All org members can use your collections
* **Generate with AI** - Let AI suggest sources based on your research needs

## Creating a Collection

1. Go to [Collections](https://platform.valyu.ai/user/collections)
2. Click **Create Collection**
3. Add sources (Valyu datasets, domains, or URLs)
4. Save with a memorable name

You can also use **Generate with AI** to automatically suggest relevant sources based on a description of your research needs.

## Using Collections

Reference collections in your API calls using the `collection:` prefix in `included_sources`:

<CodeGroup>
  ```python Python theme={null}
  from valyu import Valyu

  valyu = Valyu()
  response = valyu.search(
      query="latest quarterly earnings reports",
      included_sources=["collection:my-finance-sources"]
  )
  ```

  ```javascript TypeScript theme={null}
  import { Valyu } from 'valyu-js';

  const valyu = new Valyu();

  const response = await valyu.search(
    "latest quarterly earnings reports",
    {
      includedSources: ["collection:my-finance-sources"]
    }
  );
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.valyu.ai/v1/deepsearch \
    -H "x-api-key: your-valyu-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "latest quarterly earnings reports",
      "included_sources": ["collection:my-finance-sources"]
    }'
  ```
</CodeGroup>

## Combining Collections and Sources

Mix collections with individual sources in the same request:

<CodeGroup>
  ```python Python theme={null}
  from valyu import Valyu

  valyu = Valyu()
  response = valyu.search(
      query="biotech company clinical trial results",
      included_sources=[
          "collection:medical-research",  # Your saved collection
          "github.com/topics/artificial-intelligence",                # Additional domain
          "valyu/valyu-patents"            # Additional dataset
      ]
  )
  ```

  ```javascript TypeScript theme={null}
  import { Valyu } from 'valyu-js';

  const valyu = new Valyu();

  const response = await valyu.search(
    "biotech company clinical trial results",
    {
      includedSources: [
        "collection:medical-research",
        "github.com/topics/artificial-intelligence",
        "valyu/valyu-patents"
      ]
    }
  );
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.valyu.ai/v1/deepsearch \
    -H "x-api-key: your-valyu-api-key" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "biotech company clinical trial results",
      "included_sources": [
        "collection:medical-research",
        "github.com/topics/artificial-intelligence",
        "valyu/valyu-patents"
      ]
    }'
  ```
</CodeGroup>

## Example Collections

Here are some collection ideas to get you started:

### Financial Research Collection

Sources to include:

* `valyu/valyu-sec-filings` - SEC regulatory filings
* `valyu/valyu-stocks` - Stock market data
* `valyu/valyu-earnings-US` - Earnings reports
* `sec.gov` - Financial news
* `treasury.gov` - Market analysis

### Medical Research Collection

Sources to include:

* `valyu/valyu-pubmed` - Medical literature
* `valyu/valyu-clinical-trials` - Clinical trial data
* `valyu/valyu-drug-labels` - FDA drug information
* `nejm.org` - New England Journal of Medicine
* `thelancet.com` - The Lancet

### Tech Documentation Collection

Sources to include:

* `docs.aws.amazon.com` - AWS documentation
* `cloud.google.com/docs` - Google Cloud docs
* `learn.microsoft.com` - Microsoft docs
* `kubernetes.io/docs` - Kubernetes docs
* `developer.mozilla.org` - MDN Web Docs

## AI-Generated Collections

Use the **Generate with AI** feature on the platform to automatically suggest sources. Describe your research needs in natural language, and AI will recommend relevant Valyu datasets and domains.

For example, describe:

> "I need sources for researching biotech companies, including SEC filings, medical research papers, and news from reliable financial sources."

And AI will suggest appropriate sources like `valyu/valyu-sec-filings`, `valyu/valyu-pubmed`, `valyu/valyu-clinical-trials`, and trusted news domains.

## Visibility & Permissions

* **All organization members** can view and use any collection in their org
* **Only the creator** can edit or delete their collection
* Collections are scoped to your organization - they're not visible to other orgs

## Error Handling

If a collection doesn't exist or isn't accessible, the API returns a warning:

```json theme={null}
{
  "success": true,
  "warnings": ["Collection 'unknown-collection' not found"],
  "results": [...]
}
```

The search continues with any other valid sources you provided. If only an invalid collection was specified, you'll get empty results with the warning.

## Best Practices

<CardGroup cols={2}>
  <Card title="Use Descriptive Names" icon="tag">
    Name collections clearly: `medical-research`, `finance-sec-filings`, `tech-docs`
  </Card>

  <Card title="Keep Collections Focused" icon="bullseye">
    Create multiple small collections rather than one large catch-all
  </Card>

  <Card title="Document Your Collections" icon="file-lines">
    Add descriptions so team members understand what each collection is for
  </Card>

  <Card title="Review Periodically" icon="arrows-rotate">
    Update collections as new datasets become available or your needs change
  </Card>
</CardGroup>

## Related

* [Source Filtering](/search/filtering/sources) - Filter by individual domains and datasets
* [Date Filtering](/search/filtering/date) - Filter results by date range
* [Data Sources](https://platform.valyu.ai/data-sources) - Browse available Valyu datasets