biostudies.md
124 lines · skills/paper-lookup/references/biostudies.md at 5f2bc03
BioStudies
EMBL-EBI archive for the data outputs of a life-science study: files hosted here, plus links out to ArrayExpress, BioImages, ENA, and other archives. Use it when the user wants the dataset behind a paper, a BioStudies accession (S-BSST…, S-EPMC…, S-CMO…, E-MTAB…), or "supplementary data at EBI." It is not a paper index.
Find the paper in PubMed / Europe PMC, then come here with an accession or a keyword that appears in the study record.
The dated page-mode examples below are historical observations. Cursor pagination was verified against current help and a public two-page query on 2026-09-30.
Raw lines 1 to 13Key Endpoints
Raw lines 28 to 291. Search studies
GET /search?query={text}&page={n}&pageSize={n}GET /search?query=organoid&pageSize=2Verified: HTTP 200 with
| Field | Value on this call | Meaning |
|---|---|---|
page | 1 | 1-based |
pageSize | 2 | |
totalHits | 4195, then 4480 on a later call | Approximate |
isTotalHitsExact | false | Do not reconcile as if this were Europe PMC hitCount |
nextCursor | null in page mode | Start with pagination=cursor for a cursor walk |
hits | 2 study summaries |
A hit has accession, type (study), title, author, files (count), release_date, isPublic, content (a flattened text blob). author may be an empty string.
totalHits moved by hundreds between two calls a few seconds apart, and isTotalHitsExact stayed false. Report "about N studies" and the page you fetched. Do not claim a complete walk against that number.
Use page=2 for normal browsing. For exhaustive retrieval, use the documented cursor mode:
curl -fsS --get 'https://www.ebi.ac.uk/biostudies/api/v1/search' \
--data-urlencode 'query=organoid' \
--data-urlencode 'pagination=cursor' \
--data-urlencode 'pageSize=2'Send the opaque returned nextCursor as cursor on the next request, keeping the same query and page size. Stop at nextCursor: null; do not construct or decode cursors, or stop based on an approximate totalHits. The official example uses pageSize=1000 for bulk walks; use a small bound for interactive work. This traverses the live index, not a frozen snapshot, so record access times and deduplicate accessions.
2. One study
GET /studies/{accession}GET /studies/S-CMO2844Verified: HTTP 200. The body is not the search-hit shape:
{
"accno": "S-CMO2844",
"type": "submission",
"attributes": [{"name": "Title", …}, {"name": "ReleaseDate", …}],
"section": { "type": "Study", "accno": "s1", "attributes": […], "subsections": […] }
}Title lives in attributes (name Title), not title. Files and links are nested under section.subsections. Walk that tree; do not expect files: [ …urls ] at the top level.
A 404 means no such public accession.
Raw lines 76 to 102Typical Workflow
- Search with a paper title, accession, or biological keyword.
- Take
accessionfromhits[]. GET /studies/{accession}for the submission tree and file list.- Cite the accession and the BioStudies URL (
https://www.ebi.ac.uk/biostudies/studies/{accession}). - If they wanted the paper, go back to PubMed / Europe PMC with the title or a DOI found in the study attributes.
Failure Modes
| What you did | What happens | What to do |
|---|---|---|
Treated totalHits as exact | Count drifts; isTotalHitsExact is false | Say "about N"; do not exit-4 reconcile |
Expected search fields on /studies/{acc} | No title, no files count | Read attributes and section |
| Used BioStudies as PubMed | Studies, not articles | Search literature APIs first |
| Expected a cursor in page mode | nextCursor is null | Start with pagination=cursor; then send cursor |