# CELLxGENE Dataset Finder (`shayuyuyuyu/cellxgene-dataset-finder`) Actor

Search and filter public CZ CELLxGENE Discover single-cell datasets through the official open HTTP API. Returns metadata and asset URLs without downloading H5AD files.

- **URL**: https://apify.com/shayuyuyuyu/cellxgene-dataset-finder.md
- **Developed by:** [runze1 liu](https://apify.com/shayuyuyuyu) (community)
- **Categories:** AI, Developer tools
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 dataset results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

### What does CELLxGENE Dataset Finder do?

**CELLxGENE Dataset Finder** searches the public [CZ CELLxGENE Discover](https://cellxgene.cziscience.com) catalog of single-cell datasets through the **official open HTTP API**. It does not log in, it does not scrape private pages, and it does not download H5AD, fragment, or other data files. Each result is one dataset's metadata plus the asset URLs that the API already publishes.

The Actor calls `GET https://api.cellxgene.cziscience.com/curation/v1/datasets` once. That endpoint returns the public dataset list (about 2,300 records) as a JSON array. The OpenAPI document at `https://api.cellxgene.cziscience.com/curation/openapi.json` shows that this list accepts only `schema_version`, `visibility`, and `analysis` query parameters, so organism, tissue, disease, cell type, assay, and free-text filters are applied in the Actor after the catalog is downloaded.

### Why use CELLxGENE Dataset Finder?

Use it when you need a repeatable, agent-friendly list of public single-cell datasets before you decide which matrices to download yourself.

- Filter by organism, tissue, disease, cell type, assay, free text, and minimum cell count.
- Get stable ids, the collection DOI, the CELLxGENE Explorer link, and asset URLs with file type and size.
- Schedule runs, call the Actor from the Apify API, or connect the dataset to Make, Zapier, or your own pipeline.
- Stay on the public API. One GET, with retries on HTTP 429 and 5xx, and a hard cap so a mistaken response cannot pull a data blob.

### What data can CELLxGENE Dataset Finder extract?

| Field | Type | Description |
| --- | --- | --- |
| `datasetId` | string | Stable dataset id. It points at the latest published version. |
| `datasetVersionId` | string or null | Id of this published dataset version. |
| `collectionId` | string or null | Parent collection id. |
| `collectionName` | string or null | Collection name from the catalog. |
| `collectionDoi` | string or null | Collection DOI, when the API provides one. |
| `titleOrCitation` | string | Dataset `title`, or the `citation` when the title is blank. |
| `organism` | array of strings | Organism ontology labels, usually one value such as `Homo sapiens`. |
| `tissues` | array of strings | Tissue ontology labels. |
| `diseases` | array of strings | Disease ontology labels. |
| `cellTypes` | array of strings | Cell type ontology labels. |
| `assays` | array of strings | Assay ontology labels. |
| `cellCount` | integer or null | Number of cells reported for the dataset. |
| `explorerUrl` | string or null | Link to the dataset in CELLxGENE Explorer. |
| `publishedAt` | string or null | Publication timestamp from the API. |
| `assets` | array of objects | `{filetype, url, filesize}` for each public asset, or `[]` when `includeAssets` is false. |

Donor ids, sex, and self-reported ethnicity are not copied into the output.

### How to search CELLxGENE datasets

1. Open the Actor and go to the **Input** tab. See the input tab for full configuration options.
2. Enter any filters you need. Use ontology labels (`Homo sapiens`, `lung`, `normal`), not common names such as "human" or "mouse". Filters that you leave empty are ignored. Filters that you set are combined with AND.
3. Set **Maximum results** (default 50, maximum 500). The catalog is newest-first, and matching rows keep that order.
4. Run the Actor. Download the dataset as JSON, CSV, HTML, or Excel, or read it from the API tab.

Example input:

```json
{
  "query": "lung",
  "organism": "Homo sapiens",
  "tissue": "lung",
  "minCellCount": 1000,
  "maxResults": 15,
  "includeAssets": true
}
```

### How much will it cost to search CELLxGENE datasets?

Pay per result (configure on publish).

Each run performs a single catalog request and then writes at most `maxResults` rows (1 to 500). You are billed for the pricing model you attach when you publish the Actor. The default memory is 1024 MB, which is enough to parse the public catalog. Lower `maxResults` when you only need a short list. This repository does not enable monetization by itself.

### Input

| Field | Required | Default | Description |
| --- | --- | --- | --- |
| `query` | no | empty | Free-text substring over collection name, dataset title, citation, dataset id, and ontology labels. |
| `organism` | no | empty | Substring of organism labels. Example: `Homo sapiens`. |
| `tissue` | no | empty | Substring of tissue labels. Example: `lung`. |
| `disease` | no | empty | Substring of disease labels. Example: `normal`. |
| `cellType` | no | empty | Substring of cell type labels. Example: `macrophage`. |
| `assay` | no | empty | Substring of assay labels. Example: `10x`. |
| `minCellCount` | no | none | Keep datasets with at least this many cells. |
| `maxResults` | no | `50` | Cap on saved rows. Integer from 1 to 500. |
| `includeAssets` | no | `true` | When false, `assets` is an empty list. URLs are still not downloaded. |

Matching is a case-insensitive substring. `lung` matches `lung` and `left lung`. An empty string is treated as an omitted filter. Invalid types, a negative `minCellCount`, or a `maxResults` outside 1–500 fail the run with a message that names the field.

### Output

You can download the dataset in various formats such as JSON, HTML, CSV, or Excel.

Illustrative row (field names and types match a real run; the ids below are examples):

```json
{
  "datasetId": "00000000-0000-4000-8000-000000000001",
  "datasetVersionId": "00000000-0000-4000-8000-000000000002",
  "collectionId": "00000000-0000-4000-8000-000000000003",
  "collectionName": "Human lung cell atlas",
  "collectionDoi": "10.0000/example",
  "titleOrCitation": "lung_atlas_v1",
  "organism": ["Homo sapiens"],
  "tissues": ["lung"],
  "diseases": ["normal"],
  "cellTypes": ["macrophage"],
  "assays": ["10x 3' v3"],
  "cellCount": 5000,
  "explorerUrl": "https://cellxgene.cziscience.com/e/00000000-0000-4000-8000-000000000001.cxg/",
  "publishedAt": "2024-01-02T00:00:00+00:00",
  "assets": [
    {
      "filetype": "H5AD",
      "url": "https://datasets.cellxgene.cziscience.com/00000000-0000-4000-8000-000000000002.h5ad",
      "filesize": 1234
    }
  ]
}
```

Asset `url` values point at files hosted by CZ CELLxGENE. This Actor returns those URLs and stops. Download matrices in your own pipeline if you need them.

### Tips

- Start with `maxResults` at 15 or 50 while you tune filters. The catalog request is the same size either way; the cap only limits saved rows.
- Combine `organism` and `tissue` when a free-text `query` is too broad. `lung` also appears in citations and cell-type names.
- `includeAssets: false` keeps rows smaller when you only need ids and Explorer links.
- The run retries HTTP 429, 500, 502, 503, and 504 with backoff (1s, 2s, 4s). Other HTTP errors fail immediately with the status code.
- Local test: install the Apify CLI, then run `apify run` in this directory. Sample input is `storage/key_value_stores/default/INPUT.json`. Results land in `storage/datasets/default/` and stay on your machine.

### FAQ, disclaimers, and support

#### Does this scrape CELLxGENE or require an account?

No. It sends one unauthenticated GET to the public Discover curation API documented at [the CELLxGENE curation Swagger UI](https://api.cellxgene.cziscience.com/curation/ui/). Terms of service: <https://cellxgene.cziscience.com/tos>.

#### Why does my organism filter return nothing?

The filter matches the ontology label. Use `Homo sapiens` or `Mus musculus`, not `human` or `mouse`.

#### Are data files included?

No. `assets` lists `filetype`, `url`, and `filesize` only. H5AD and ATAC fragment files are not downloaded.

This Actor reads public catalog metadata that CZ CELLxGENE already distributes. It does not collect private account data, and it does not copy donor identifiers into the dataset. Collection names and citations can still name researchers because that text is part of the public catalog. Personal data is protected by the GDPR in the European Union and by other regulations around the world. Do not reuse that text as personal data unless you have a legitimate reason to do so.

Questions and bugs belong on the Actor's **Issues** tab. Programmatic runs use the **API** tab of the Actor page.

# Actor input Schema

## `query` (type: `string`):

Case-insensitive substring matched against collection name, dataset title, citation, dataset ID, and the ontology labels for organism, tissue, disease, cell type, and assay.

## `organism` (type: `string`):

Substring matched against organism ontology labels, for example Homo sapiens or Mus musculus. Common names such as human or mouse are not translated.

## `tissue` (type: `string`):

Substring matched against tissue ontology labels, for example lung, liver, or cortex.

## `disease` (type: `string`):

Substring matched against disease ontology labels, for example normal, COVID-19, or carcinoma.

## `cellType` (type: `string`):

Substring matched against cell type ontology labels, for example macrophage, T cell, or neuron.

## `assay` (type: `string`):

Substring matched against assay ontology labels, for example 10x, snRNA-seq, or Slide-seq.

## `minCellCount` (type: `integer`):

Keep datasets whose cell_count is greater than or equal to this value.

## `maxResults` (type: `integer`):

Maximum number of dataset rows to save. The public catalog is newest-first, and that order is kept.

## `includeAssets` (type: `boolean`):

Include each asset's filetype, URL, and file size. The Actor does not download those files.

## Actor input object example

```json
{
  "query": "lung",
  "organism": "Homo sapiens",
  "maxResults": 50,
  "includeAssets": true
}
```

# Actor output Schema

## `datasets` (type: `string`):

Filtered CELLxGENE dataset metadata, one item per dataset.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "query": "lung",
    "organism": "Homo sapiens"
};

// Run the Actor and wait for it to finish
const run = await client.actor("shayuyuyuyu/cellxgene-dataset-finder").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "query": "lung",
    "organism": "Homo sapiens",
}

# Run the Actor and wait for it to finish
run = client.actor("shayuyuyuyu/cellxgene-dataset-finder").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "query": "lung",
  "organism": "Homo sapiens"
}' |
apify call shayuyuyuyu/cellxgene-dataset-finder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,shayuyuyuyu/cellxgene-dataset-finder"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/Eu15cKWTGTZftblck/builds/PCgGXlOcWvAXfsMIb/openapi.json