Skip to main content
alphacast.search.datasets() runs a full-text search against Alphacast’s catalog. By default it scopes to datasets your account has read access to (your own repositories plus anything you’ve been granted access to). Pass search_all=True to extend the search to every public dataset on Alphacast. 
from alphacast import Alphacast

alphacast = Alphacast("YOUR_API_KEY")
results = alphacast.search.datasets("GDP Argentina")

for ds in results["data"]:
    print(ds["id"], ds["name"])

​
Method signature

search.datasets(
    query,
    offset=0,
    length=10,
    repository_id=None,
    search_all=False,
    exclude_deprecated=False,
)
​
query
str
required
Free-text search. Supports fuzzy matching, so close spellings still rank.
​
offset
int
default:"0"
Number of results to skip. Use with length for pagination.
​
length
int
default:"10"
Maximum number of results to return.
​
repository_id
int
Restrict results to a single repository.
​
search_all
bool
default:"False"
When True, search every public dataset on Alphacast. When False, search only datasets your account can already read.
​
exclude_deprecated
bool
default:"False"
When True, omit datasets flagged as deprecated.

​
Response shape

The method returns a dict: 
{
  "data": [...],         # list of matching datasets
  "totalItems": 124,     # total matches across all pages
  "totalPages": 13,
  "currentPage": 1,
  "offset": 0,
}
Each entry in data includes the dataset’s id, name, description, source metadata, and other fields the search service returns. Use the id to feed dataset(id) for further reads.

​
Examples

​
Paginate through results

page1 = alphacast.search.datasets("inflation", offset=0, length=10)
page2 = alphacast.search.datasets("inflation", offset=10, length=10)

print(f"Showing {len(page1['data'])} of {page1['totalItems']} results")

​
Search the entire public catalog

results = alphacast.search.datasets("CPI", search_all=True)
Useful when you want to discover datasets you don’t already have access to. Public results can be downloaded directly with dataset(id).download_data(...).

​
Filter by repository

results = alphacast.search.datasets("employment", repository_id=42)

​
Exclude deprecated datasets

results = alphacast.search.datasets("GDP", exclude_deprecated=True)

​
Search results → download

A common pattern is to search, pick a result, and pull the data: 
results = alphacast.search.datasets("Argentina inflation", search_all=True, length=5)

# Take the top hit
top = results["data"][0]
print("Selected:", top["id"], top["name"])

df = alphacast.datasets.dataset(top["id"]).download_data(format="pandas")

​
Notes on the underlying endpoint

search.datasets() calls the Alphacast workspace search endpoint at https://www.alphacast.io/api/search, not the standard REST API on api.alphacast.io. The SDK passes your API key as an apiKey query parameter on this endpoint — the search service does not currently support HTTP Basic Auth. Permissions are still respected: you only see what your key is authorized to read, plus any public content if search_all=True.

​
Next steps