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

# Search & Datasets Tools

> Tools for discovering content in the Alphacast catalog, reading dataset metadata, schemas, and rows, and resolving the workspace's default repository.

These eight tools cover discovery and read access. None of them mutate state, so you can safely chain them together to explore Alphacast.

## `search_catalog`

Search the curated Alphacast catalog (default) or every public repository.

<ParamField body="query" type="string" required>
  Search query. Tokenized server-side; multi-word queries score every term.
</ParamField>

<ParamField body="asset" type="string" default="datasets">
  Type of asset to return. One of `datasets`, `charts`, `insights`, `repositories`, `accounts`, `dashboards`, `series`, `tickers`.
</ParamField>

<ParamField body="limit" type="number" default="10">
  Maximum number of results.
</ParamField>

<ParamField body="offset" type="number" default="0">
  Pagination offset.
</ParamField>

<ParamField body="tags" type="string[]">
  Optional list of tag slugs to filter by.
</ParamField>

<ParamField body="repositoryId" type="number">
  Optional repository ID to scope the search to a single repo.
</ParamField>

<ParamField body="searchAllAlphacast" type="boolean" default="false">
  Set to `true` to search every public repository instead of just the curated catalog.
</ParamField>

<ParamField body="excludeDeprecated" type="boolean" default="false">
  When `true`, deprecated datasets are excluded from results.
</ParamField>

**Example prompt**

> "Find Argentina inflation series in the curated catalog."

**Underlying endpoint:** `GET /api/search`.

***

## `get_dataset`

Retrieve dataset metadata and the column schema.

<ParamField body="datasetId" type="number" required>
  Numeric dataset ID. Strings are coerced.
</ParamField>

Returns the dataset's name, description, repository, last update timestamp, and the column array (`name`, `dataType`, `isEntity`).

**Example prompt**

> "Show me the schema of dataset 12345."

**Underlying endpoints:** `GET /datasets/{id}` + `GET /datasets/{id}/columns` (called in parallel).

***

## `download_dataset`

Download the current rows of a dataset.

<ParamField body="datasetId" type="number" required>
  Numeric dataset ID.
</ParamField>

<ParamField body="format" type="string" default="json">
  `json` returns an array of objects. `csv` returns a CSV string.
</ParamField>

Internally follows S3 redirects so the model receives the raw rows directly.

**Example prompt**

> "Download dataset 12345 as CSV and tell me the date range."

**Underlying endpoint:** `GET /datasets/{id}/data?$format=...`.

***

## `list_datasets`

List every dataset the API key can read.

No input parameters. Returns one row per dataset with `id`, `name`, `repositoryId`, and `frequency`.

**Example prompt**

> "List all datasets I have access to and pick the ones tagged 'Argentina'."

**Underlying endpoint:** `GET /datasets`.

***

## `list_repositories`

List repositories where the API key can publish (Owner, Admin, or Write).

No input parameters. Filtered server-side; read-only repositories are excluded so the model only sees repositories it can write to.

<Tip>
  Tools that accept an optional `repositoryId` (for example [`create_pipeline`](/mcp/tools/pipelines#create_pipeline)) **default to the workspace's default repository** when no ID is provided — the server does not interrupt to ask you to pick one. Call `list_repositories` only when you want to write somewhere other than the default, or `get_default_repository` to check which repo the default resolves to.
</Tip>

**Example prompt**

> "Which repos can I publish into?"

**Underlying endpoint:** `GET /repositories` (with client-side permission filter).

***

## `get_repository`

Retrieve a single repository's metadata.

<ParamField body="repositoryId" type="number" required>
  Numeric repository ID.
</ParamField>

Returns name, description, privacy, your permission level, and timestamps.

**Example prompt**

> "What's the description of repository 1042 and who owns it?"

**Underlying endpoint:** `GET /repositories/{id}`.

***

## `get_default_repository`

Resolve the **default repository** — the current writable repository for this API key's active workspace, where pipelines and datasets land when no specific repository is named. Use it to inspect what the default points at before creating a pipeline, or to share its ID with collaborators.

No input parameters. Returns the repository as if you had called `get_repository` on it.

**Example prompt**

> "What's my default Alphacast repository?"

**Underlying endpoint:** `GET /repositories/default`.

***

## `get_dataset_profile`

Comprehensive inspection of a dataset: column schema, entity values, date range and frequency, total row count, and a sample of rows. Use this for a quick understanding of what a dataset contains before downloading it.

<ParamField body="datasetId" type="number" required>
  Numeric dataset ID.
</ParamField>

<ParamField body="sampleRows" type="number" default="10">
  Number of sample rows to include in the response. Maximum 50. Set to `0` to skip the sample entirely.
</ParamField>

Returns `dataset` metadata, `columns`, `entities`, `dateStats` (date range and frequency), `rowCount`, and a `sample` array. Individual sections gracefully degrade if unavailable.

**Example prompt**

> "Profile dataset 12345 — how many rows does it have, what entities does it cover, and show me 5 sample rows."

**Underlying endpoints:** `GET /datasets/{id}` + `GET /datasets/{id}/columns` + `GET /datasets/{id}/entities` + `GET /datasets/{id}/date-stats` + `GET /datasets/{id}/data?$top=N` (called in parallel).