CELLxGENE Dataset Finder

What does CELLxGENE Dataset Finder do?

CELLxGENE Dataset Finder searches the public CZ CELLxGENE Discover 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:

{
  "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):

{
  "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. 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.