Search the Catalogue

Use client.search() to locate items in the data catalogue. The method returns a pandas DataFrame with metadata for each match.

Basic search

from atomscale import Client

client = Client(api_key="YOUR_API_KEY")

results = client.search(keywords=["WSe2"])
print(results[["Data ID", "Status", "Sample Name"]])

Limit to your uploads

By default, search includes data from other users in your organization. To see only your own uploads:

personal_only = client.search(
    keywords="demo",
    include_organization_data=False,
)

Filter by IDs or type

Fetch specific items by their data IDs:

exact = client.search(data_ids=["44fa63b0-74da-4d25-a362-2276c80a670a"])

Filter by data type:

videos = client.search(data_type="rheed")

RHEED videos share the single rheed type whether or not the stage was rotating. To tell them apart, fetch the results with client.get() and check the rotating property of each RHEEDVideoResult, which is read from the stored rotation rate.

Available data types

Value	Description
`rheed_image`	Single RHEED image
`rheed`	RHEED video, stationary or rotating
`rheed_stationary`, `rheed_rotating`	Legacy aliases for `rheed`. Both match all RHEED videos, rotating or not
`xps`	XPS spectrum
`xrd`	XRD pattern
`photoluminescence`	Photoluminescence spectrum
`pl`	Alias for photoluminescence
`raman`	Raman spectrum
`ellipsometry`	Ellipsometry measurement
`optical`	Optical imaging
`tool_state`	Tool-state log (instrument sensor readbacks)
`metrology`	Deprecated alias for `tool_state`
`recipe`	Growth recipe
`all`	All types (default)

Filter by lifecycle state

The status parameter filters by pipeline state:

completed = client.search(status="success")

Available status values

Value	Description
`success`	Analysis completed successfully
`pending`	Queued for processing
`running`	Currently processing
`error`	Analysis failed
`stream_active`	Streaming in progress
`stream_interrupted`	Stream was interrupted
`stream_finalizing`	Stream finishing up
`stream_error`	Streaming failed
`all`	All statuses (default)

Apply numeric or datetime bounds

Pass (min, max) tuples for growth length (seconds), upload timestamp, or last-updated timestamp. Use None for an open bound.

from datetime import datetime

recent = client.search(
    upload_datetime=(datetime(2025, 1, 1), None),
    last_updated=(datetime(2025, 6, 1), None),
    growth_length=(3000, None),
)

last_accessed_datetime is a deprecated alias for last_updated. It still works but emits a warning, and it will be removed in a future release.

Combine filters

All filter parameters can be combined:

results = client.search(
    keywords="GaN",
    data_type="rheed",
    status="success",
    upload_datetime=(datetime(2025, 1, 1), None),
)

Result columns

Each row describes one catalogue entry:

Column	Description
`Data ID`	Unique identifier, the input to `client.get()`
`File Name`, `File Type`, `File Metadata`	Source file and format details
`Type`, `Status`	Data type and pipeline state
`Instrument Source`, `Has Instrument Logs`	Originating instrument and log availability
`Sample Name`, `Physical Sample ID/Name`	Linked sample
`Sample Notes`, `Sample Notes Last Updated`	Sample annotations
`Project ID`, `Project Name`	Linked project
`Tags`	Tags attached to the item
`Growth Length`	Duration in seconds, for videos
`Collected Datetime`, `Upload Datetime`, `Last Updated`	Lifecycle timestamps
`Owner`, `Workspaces`	Ownership and visibility

Next steps

Pass the Data ID column to client.get() to fetch analysis artefacts. See Inspect Results for a hands-on tour.

Introduction

Guides

References

Basic search

Limit to your uploads

Filter by IDs or type

Available data types

Filter by lifecycle state

Available status values

Apply numeric or datetime bounds

Combine filters

Result columns

Next steps

​Basic search

​Limit to your uploads

​Filter by IDs or type

​Available data types

​Filter by lifecycle state

​Available status values

​Apply numeric or datetime bounds

​Combine filters

​Result columns

​Next steps

Basic search

Limit to your uploads

Filter by IDs or type

Available data types

Filter by lifecycle state

Available status values

Apply numeric or datetime bounds

Combine filters

Result columns

Next steps