Literature, preprint and clinical study queries: parameters and notes¶
See the tutorial for usage and examples.
Each function includes its purpose, API, inputs, outputs, example code and result description. Prepare any required credentials, local files and optional dependencies; remote results vary with database releases and query time.
Search arXiv papers by keyword¶
dnakit.databases.ar_xiv_search_papers(*, query, limit=None, sort_by=None, sort_order=None, date_from=None, date_to=None, category=None, verbose=True)
| Parameter | Type | Required / default | Description and constraints |
|---|---|---|---|
query |
string | Required | Search query for arXiv papers. Unquoted, unprefixed space-separated keywords are ANDed together (every keyword must match) -- adding more keywords NARROWS results, it does not broaden them. To search multiple synonyms/phrases and broaden recall, join them with explicit OR, e.g. '"machine learning" OR "deep learning" OR "neural networks"'. Supports field prefixes (au:, ti:, abs:, cat:, all:) and AND/OR/ANDNOT boolean operators, which are passed through as-is. |
limit |
integer | None | Number of papers to return. This sets the maximum number of papers retrieved from arXiv. |
sort_by |
string | None | Sort order for results. Options: 'relevance', 'lastUpdatedDate', 'submittedDate' |
sort_order |
string | None | Sort direction. Options: 'ascending', 'descending' |
date_from |
string | None | Filter results from this date (format: YYYY-MM-DD). Uses submittedDate, the date of the paper's FIRST version -- a paper revised/updated after this date but originally submitted earlier is still excluded. |
date_to |
string | None | Filter results up to this date (format: YYYY-MM-DD). Uses submittedDate, the date of the paper's FIRST version -- a paper revised/updated after this date but originally submitted earlier is still included. |
category |
string | None | Category or result class defined by this operation's provider/schema. |
verbose |
bool | True | Progress flag. |
Retrieve bioRxiv preprint metadata by DOI¶
dnakit.databases.bio_rxiv_get_preprint(*, doi, server=None, verbose=True)
| Parameter | Type | Required / default | Description and constraints |
|---|---|---|---|
doi |
string | Required | bioRxiv or medRxiv DOI. Can be full DOI (e.g., '10.1101/2023.12.01.569554') or just the numeric part after '10.1101/' (e.g., '2023.12.01.569554'). Find DOIs using EuropePMC_search_articles, web_search, or from paper citations. |
server |
string | None | Server to query: 'biorxiv' for bioRxiv preprints or 'medrxiv' for medRxiv preprints. Default is 'biorxiv'. |
verbose |
bool | True | Progress flag. |
List recent preprints within a date range¶
dnakit.databases.bio_rxiv_list_recent_preprints(*, start_date=None, end_date=None, server=None, cursor=None, query=None, limit=None, verbose=True)
| Parameter | Type | Required / default | Description and constraints |
|---|---|---|---|
start_date |
string | None | Start date in YYYY-MM-DD format (e.g., '2024-01-01'). Date range must not exceed 60 days. |
end_date |
string | None | End date in YYYY-MM-DD format (e.g., '2024-01-03'). Date range must not exceed 60 days. |
server |
string | None | Server: 'biorxiv' for biology preprints, 'medrxiv' for health sciences preprints |
cursor |
integer | None | Pagination cursor (0 for first 100 results, 100 for next 100, etc.) |
query |
string | None | Search term or expression in the current provider's query syntax. |
limit |
integer | None | Maximum results for the current request, not a database-wide total. |
verbose |
bool | True | Progress flag. |
Search clinical studies by condition, intervention or sponsor¶
dnakit.databases.clinical_trials_search_studies(*, operation=None, query_cond=None, query_intr=None, query_term=None, filter_status=None, filter_phase=None, filter_study_type=None, page_size=None, next_page_token=None, query=None, condition=None, status=None, max_results=None, intervention=None, sponsor=None, verbose=True)
| Parameter | Type | Required / default | Description and constraints |
|---|---|---|---|
operation |
string | None | Operation (optional; defaults to 'search' for this tool). |
query_cond |
string | null | None | Disease or condition to search for (e.g., 'breast cancer', 'type 2 diabetes', 'COVID-19'). Supports Boolean operators (AND, OR, NOT). Multi-word values are matched as an exact phrase (e.g. 'kidney transplantation' is sent as "kidney transplantation"), which is narrower than a loose keyword match. For looser matching, wrap the value in parentheses (e.g. '(kidney transplantation)') to send it verbatim. Values already containing Essie syntax (AND/OR/NOT/AREA[]/quotes) are passed through unchanged. See executed_query in the response for what actually ran. |
query_intr |
string | null | None | Intervention or drug to search for (e.g., 'pembrolizumab', 'metformin', 'chemotherapy'). Matched against each study's registered intervention names and synonyms (InterventionName/InterventionOtherName), not free text in study summaries, and multi-word values are matched as an EXACT PHRASE -- so 'donor derived cell therapy' matches 0 studies even though 251 trials match the same words loosely. For looser matching, wrap the value in parentheses (e.g. '(donor derived cell therapy)') to send it verbatim, or use ClinicalTrials_search_studies with query_term for free text across all study fields. Prefer the generic/INN name over a brand name. See executed_query and relaxed_match_check in the response. |
query_term |
string | null | None | Free-text search across all study fields. Use for general keyword search. |
filter_status |
string | null | None | Filter by recruitment status. Options: 'RECRUITING', 'NOT_YET_RECRUITING', 'ACTIVE_NOT_RECRUITING', 'COMPLETED', 'WITHDRAWN', 'SUSPENDED', 'TERMINATED', 'ENROLLING_BY_INVITATION'. Comma-separate multiple values. |
filter_phase |
string | null | None | Filter by trial phase. Options: 'EARLY_PHASE1', 'PHASE1', 'PHASE2', 'PHASE3', 'PHASE4', 'NA'. Comma-separate multiple (e.g., 'PHASE2,PHASE3'). |
filter_study_type |
string | null | None | Filter by study type: 'INTERVENTIONAL', 'OBSERVATIONAL', 'EXPANDED_ACCESS'. |
page_size |
integer | None | Number of results per page (default 10, max 1000). |
next_page_token |
string | null | None | Token for retrieving the next page of results (obtained from previous response). |
query |
string | null | None | General keyword search across all fields. Alias for query_term. E.g., "FLT3 AML", "KRAS NSCLC". |
condition |
string | null | None | Disease or condition to search for. Alias for query_cond. E.g., "acute myeloid leukemia". Multi-word values are matched as an exact phrase (e.g. 'kidney transplantation' is sent as "kidney transplantation"), which is narrower than a loose keyword match. For looser matching, wrap the value in parentheses (e.g. '(kidney transplantation)') to send it verbatim. Values already containing Essie syntax (AND/OR/NOT/AREA[]/quotes) are passed through unchanged. See executed_query in the response for what actually ran. |
status |
string | null | None | Recruitment status filter. Alias for filter_status. E.g., "RECRUITING", "COMPLETED". |
max_results |
integer | null | None | Maximum number of results to return. Alias for page_size. |
intervention |
string | null | None | Intervention or drug to search for. Alias for query_intr. E.g., "pembrolizumab", "metformin". Matched against each study's registered intervention names and synonyms (InterventionName/InterventionOtherName), not free text in study summaries, and multi-word values are matched as an EXACT PHRASE -- so 'donor derived cell therapy' matches 0 studies even though 251 trials match the same words loosely. For looser matching, wrap the value in parentheses (e.g. '(donor derived cell therapy)') to send it verbatim, or use ClinicalTrials_search_studies with query_term for free text across all study fields. Prefer the generic/INN name over a brand name. See executed_query and relaxed_match_check in the response. |
sponsor |
string | null | None | Lead sponsor or collaborator name to search for. E.g., "National Cancer Institute". Matched against each study's registered lead-sponsor name (AREA[LeadSponsorName]) only, and multi-word values are matched as an EXACT PHRASE. For looser matching, wrap the value in parentheses (e.g. '(National Cancer Institute)') to send it verbatim. See executed_query and relaxed_match_check in the response. |
verbose |
bool | True | Progress flag. |
Search Crossref publications and DOI metadata¶
dnakit.databases.crossref_search_works(*, query, limit=None, offset=None, filter=None, verbose=True)
| Parameter | Type | Required / default | Description and constraints |
|---|---|---|---|
query |
string | Required | Search query for Crossref works. Use keywords separated by spaces to refine your search across titles, abstracts, authors, and other bibliographic fields. |
limit |
integer | None | Number of articles to return in this page. This sets the maximum number of articles retrieved from Crossref. Max 100 per request. It does not change 'total_count', which always reports how many works match the query. |
offset |
integer | None | Skip this many matching works before returning results. Use with 'limit' to page through a result set larger than 100; the response 'truncation_note' gives the offset for the next page. |
filter |
string | None | Optional filter string for Crossref API. Examples: 'type:journal-article' (only journal articles), 'from-pub-date:2020-01-01' (published after date), 'has-abstract:true' (only with abstracts). Multiple filters comma-separated. |
verbose |
bool | True | Progress flag. |
Search Europe PMC articles and abstracts¶
dnakit.databases.europe_pmc_search_articles(*, query, limit=None, require_has_ft=None, fulltext_terms=None, enrich_missing_abstract=None, extract_terms_from_fulltext=None, page_size=None, pageSize=None, source=None, verbose=True)
| Parameter | Type | Required / default | Description and constraints |
|---|---|---|---|
query |
string | Required | Search query for Europe PMC. Supports Lucene-like fielded syntax (e.g., BODY:"term", INTRO:"term", METHODS:"term"). |
limit |
integer | None | Number of articles to return. This sets the maximum number of articles retrieved from Europe PMC; anything beyond it is silently left behind, so compare it against metadata.total_results in the response (Europe PMC's hitCount) before treating the returned set as complete. Europe PMC accepts up to 1000 per request. |
require_has_ft |
boolean | None | If true, appends HAS_FT:Y to the query to restrict results to records where Europe PMC has full text indexed. This is NOT the same as having a link to free full text elsewhere (e.g., PMC) and is often the key reason body-only keywords cannot be found via Europe PMC search. |
fulltext_terms |
array | None | Optional list of terms that must occur in the indexed full text (Europe PMC BODY field). When provided, the tool adds a BODY:"..." clause and automatically enables require_has_ft. {"items": {"type": "string"}} |
enrich_missing_abstract |
boolean | None | If true, best-effort fills missing abstracts by fetching Europe PMC fullTextXML (bounded to a few results). |
extract_terms_from_fulltext |
array | None | Optional list of terms to extract from full text (open access only). When provided, automatically fetches fullTextXML for open-access articles and returns snippets around these terms. Terms are processed in batches of 5 internally, so any number of terms is accepted. Bounded to first 3 OA articles to avoid latency. Returns snippets in a 'fulltext_snippets' field for each article. {"items": {"type": "string"}} |
page_size |
integer | None | Alias for limit — number of results to return |
pageSize |
integer | None | DNAKit optional alias for limit |
source |
string | None | Source filter using values accepted by this operation. |
verbose |
bool | True | Progress flag. |
Retrieve medRxiv preprint metadata by DOI¶
dnakit.databases.med_rxiv_get_preprint(*, doi=None, server=None, query=None, limit=None, verbose=True)
| Parameter | Type | Required / default | Description and constraints |
|---|---|---|---|
doi |
string | None | medRxiv DOI. Can be full DOI (e.g., '10.1101/2021.04.29.21256344') or just the numeric part after '10.1101/' (e.g., '2021.04.29.21256344'). Find DOIs using EuropePMC_search_articles, web_search, or from paper citations. |
server |
string | None | Server to query - always 'medrxiv' for this tool. |
query |
string | None | Search term or expression in the current provider's query syntax. |
limit |
integer | None | Maximum results for the current request, not a database-wide total. |
verbose |
bool | True | Progress flag. |
Retrieve OpenAlex author details¶
dnakit.databases.openalex_get_author(*, author_id, mailto=None, verbose=True)
| Parameter | Type | Required / default | Description and constraints |
|---|---|---|---|
author_id |
string | Required | OpenAlex Author ID (A...) or full OpenAlex URL. |
mailto |
string | None | Optional contact email for OpenAlex polite pool. |
verbose |
bool | True | Progress flag. |
Search scholarly literature with OpenAlex¶
dnakit.databases.openalex_literature_search(*, search_keywords=None, query=None, max_results=None, limit=None, num_results=None, year_from=None, start_year=None, year_to=None, end_year=None, open_access=None, require_has_fulltext=None, fulltext_terms=None, verbose=True)
| Parameter | Type | Required / default | Description and constraints |
|---|---|---|---|
search_keywords |
string | None | Keywords to search for in paper titles/abstracts/etc. For full-text-index-only matching, also use require_has_fulltext/fulltext_terms. |
query |
string | None | Alias for search_keywords (recommended when you standardize on query across multiple paper-search tools). |
max_results |
integer | None | Maximum number of papers to retrieve (default: 10, maximum: 200). |
limit |
integer | None | Alias for max_results (OpenAlex max 200). |
num_results |
integer | None | Alias for max_results (OpenAlex max 200). |
year_from |
integer | None | Start year for publication date filter (e.g., 2020). Optional parameter to limit search to papers published from this year onwards. |
start_year |
integer | None | Alias for year_from. |
year_to |
integer | None | End year for publication date filter (e.g., 2023). Optional parameter to limit search to papers published up to this year. |
end_year |
integer | None | Alias for year_to. |
open_access |
boolean | None | Filter for open access papers only. Set to true for open access papers, false for non-open access, or omit for all papers. |
require_has_fulltext |
boolean | None | If true, filters to works where OpenAlex indicates a full-text index is available (has_fulltext:true). |
fulltext_terms |
array | None | Optional list of terms that must occur in OpenAlex full-text index (adds fulltext.search:<term> filters and implicitly enables require_has_fulltext). {"items": {"type": "string"}} |
verbose |
bool | True | Progress flag. |
Provide at least one of these parameter groups: search_keywords; query.
Search OpenAlex works with filters¶
dnakit.databases.openalex_search_works(*, search=None, query=None, filter=None, require_has_fulltext=None, fulltext_terms=None, per_page=None, limit=None, page=None, sort=None, mailto=None, verbose=True)
| Parameter | Type | Required / default | Description and constraints |
|---|---|---|---|
search |
string | None | Search query for works. Use filter + fulltext_terms/require_has_fulltext when you need full-text-index-only matching. |
query |
string | None | Alias for search (recommended when you standardize on query across multiple paper-search tools). |
filter |
string | None | OpenAlex filter string (comma-separated). Example: "from_publication_date:2020-01-01,is_oa:true". |
require_has_fulltext |
boolean | None | If true, appends OpenAlex filter has_fulltext:true (keeps only works with full-text index available). |
fulltext_terms |
array | None | Optional list of terms to match in OpenAlex full-text index. Adds one or more fulltext.search:<term> filters and implicitly enables require_has_fulltext. {"items": {"type": "string"}} |
per_page |
integer | None | Results per page (OpenAlex max 200). |
limit |
integer | None | Alias for per_page (OpenAlex max 200). |
page |
integer | None | Page number (1-indexed). |
sort |
string | None | Sort order string, e.g. "cited_by_count:desc". |
mailto |
string | None | Optional contact email for OpenAlex polite pool. If omitted, ToolUniverse uses a default. |
verbose |
bool | True | Progress flag. |
Provide at least one of these parameter groups: search; query.
Retrieve full PubMed article metadata by PMID¶
dnakit.databases.pub_med_get_article(*, pmid, verbose=True)
| Parameter | Type | Required / default | Description and constraints |
|---|---|---|---|
pmid |
string | integer | Required | PubMed ID (PMID) as string or integer (e.g., '12345678' or 12345678, '33250470' or 33250470). Find PMIDs using PubMed_search_articles. Can also accept comma-separated PMIDs as string for multiple articles. |
verbose |
bool | True | Progress flag. |
Find articles citing a PubMed paper¶
dnakit.databases.pub_med_get_cited_by(*, pmid, limit=None, verbose=True)
| Parameter | Type | Required / default | Description and constraints |
|---|---|---|---|
pmid |
string | Required | PubMed ID (PMID) for which to find citing articles (e.g., '12345678'). Find PMIDs using PubMed_search_articles. |
limit |
integer | None | Maximum number of citing articles to return (default: 20, max: 100). |
verbose |
bool | True | Progress flag. |
Find articles related to a PubMed paper¶
dnakit.databases.pub_med_get_related(*, pmid, limit=None, verbose=True)
| Parameter | Type | Required / default | Description and constraints |
|---|---|---|---|
pmid |
string | Required | PubMed ID (PMID) for which to find related articles (e.g., '20210808', '19879512'). Find PMIDs using PubMed_search_articles. |
limit |
integer | None | Maximum number of related articles to return (default: 20, max: 100). |
verbose |
bool | True | Progress flag. |
Search PubMed biomedical literature¶
dnakit.databases.pub_med_search_articles(*, query, limit=None, mindate=None, maxdate=None, datetype=None, include_abstract=None, sort=None, max_results=None, verbose=True)
| Parameter | Type | Required / default | Description and constraints |
|---|---|---|---|
query |
string | Required | Search query for PubMed articles. Use keywords, author names, journal names, or MeSH terms. Examples: 'cancer immunotherapy', 'Smith J[Author]', 'Nature[Journal]', 'diabetes[MeSH]'. Use AND/OR/NOT for complex queries. Note: PubMed ANDs every space-separated keyword by default, so a long, highly specific free-text query (5+ concepts) often returns 0 results even when relevant literature exists. Prefer 2-4 key concepts, add explicit OR for synonyms, or try EuropePMC_search_articles for broader relevance-ranked full-text search if this returns 0 results. |
limit |
integer | None | Number of articles to return. This sets the maximum number of articles retrieved from PubMed (max: 200). |
mindate |
string | None | Minimum date for results (format: YYYY/MM/DD or YYYY). Requires datetype to be set. |
maxdate |
string | None | Maximum date for results (format: YYYY/MM/DD or YYYY). Requires datetype to be set. |
datetype |
string | None | Type of date to filter on: 'pdat' (publication date), 'edat' (Entrez date), or 'mdat' (modification date). Required when using mindate/maxdate. |
include_abstract |
boolean | None | If true, best-effort fetches abstracts via efetch (adds abstract/abstract_source fields). |
sort |
string | None | Sort order for results. Valid values: 'pub_date' (newest first), 'Author' (alphabetical by first author), 'JournalName' (alphabetical by journal), 'relevance' (default PubMed ranking). |
max_results |
integer | None | Alias for limit — maximum number of results to return |
verbose |
bool | True | Progress flag. |
Find clinical trials by disease, drug or keyword¶
dnakit.databases.search_clinical_trials(*, condition=None, intervention=None, query_term=None, pageSize=None, pageToken=None, overall_status=None, max_results=None, limit=None, status=None, keyword=None, verbose=True)
| Parameter | Type | Required / default | Description and constraints |
|---|---|---|---|
condition |
string | None | Query for condition or disease using Essie expression syntax (e.g., 'lung cancer', '(head OR neck) AND pain AND NOT "back pain"'). Sent to ClinicalTrials.gov verbatim (this tool does not rewrite condition values); see executed_query in the response for what actually ran. |
intervention |
string | None | Query for intervention/treatment using Essie expression syntax (e.g., 'chemotherapy', 'immunotherapy', 'olaparib', 'combination therapy'). Matched against each study's registered intervention names and synonyms (InterventionName/InterventionOtherName), not free text in study summaries, so prefer the generic/INN name: a brand name that no registrant recorded in either field can return zero results. Values that already contain Essie syntax (AREA[...]/AND/OR/NOT/quotes) are passed through unchanged. Matched against each study's registered intervention names and synonyms (InterventionName/InterventionOtherName), not free text in study summaries, and multi-word values are matched as an EXACT PHRASE -- so 'donor derived cell therapy' matches 0 studies even though 251 trials match the same words loosely. For looser matching, wrap the value in parentheses (e.g. '(donor derived cell therapy)') to send it verbatim, or use ClinicalTrials_search_studies with query_term for free text across all study fields. Prefer the generic/INN name over a brand name. See executed_query and relaxed_match_check in the response. |
query_term |
string | None | Query for 'other terms' with Essie expression syntax (e.g., 'combination', 'AREA[LastUpdatePostDate]RANGE[2023-01-15,MAX]', 'Phase II'). Can be used to search for all other protocol fields, including but not limited to title, outcome measures, status, phase, location, etc. |
pageSize |
integer | None | Maximum number of studies to return per page (default 10, max 1000). |
pageToken |
string | None | Token to retrieve the next page of results, obtained from the 'nextPageToken' field of the previous response. Do not specify it for first page. When you make an initial request to the API which supports pagination, the response will include a nextPageToken. This token can then be used as a parameter in the subsequent API request to retrieve the next set of data. |
overall_status |
array | None | Filter by overall study status (e.g., ['RECRUITING'], ['COMPLETED'], ['RECRUITING', 'NOT_YET_RECRUITING']). Valid values: RECRUITING, NOT_YET_RECRUITING, ACTIVE_NOT_RECRUITING, COMPLETED, ENROLLING_BY_INVITATION, SUSPENDED, TERMINATED, WITHDRAWN. {"items": {"type": "string"}} |
max_results |
integer | None | Maximum number of studies to return (alias for pageSize, default 10, max 1000). |
limit |
integer | None | Alias for max_results: maximum number of studies to return (default 10, max 1000). |
status |
object | None | None | Alias for overall_status. Filter by trial status, e.g. "RECRUITING", "COMPLETED". {"oneOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}]} |
keyword |
string | None | Alias for query_term. Free-text keyword search across all trial fields (e.g., drug name, condition, investigator). |
verbose |
bool | True | Progress flag. |
Search papers, abstracts and summaries with Semantic Scholar¶
dnakit.databases.semantic_scholar_search_papers(*, query, limit=None, year=None, sort=None, include_abstract=None, verbose=True)
| Parameter | Type | Required / default | Description and constraints |
|---|---|---|---|
query |
string | Required | Search query for Semantic Scholar. Use keywords separated by spaces to refine the search. |
limit |
integer | None | Maximum number of papers to return from Semantic Scholar. |
year |
string | None | Filter results by publication year. Use a single year (e.g., '2024') or a range (e.g., '2020-2024'). |
sort |
string | None | Sort results. Options: 'citationCount:desc', 'citationCount:asc', 'publicationDate:desc', 'publicationDate:asc'. |
include_abstract |
boolean | None | If true, best-effort fetches missing abstracts via the paper detail endpoint (only when abstract is missing in search results). |
verbose |
bool | True | Progress flag. |
Search the web using search engines¶
dnakit.databases.web_search(*, query, max_results=None, search_type=None, backend=None, region=None, safesearch=None, verbose=True)
| Parameter | Type | Required / default | Description and constraints |
|---|---|---|---|
query |
string | Required | Search query string |
max_results |
integer | None | Maximum number of results to return |
search_type |
string | None | Type of search to perform |
backend |
string | None | Search engine backend to use. Selecting 'parallel' sends the query to https://search.parallel.ai/mcp; that backend does not apply ToolUniverse region or safesearch controls. Selecting 'serpbase' sends the query to https://api.serpbase.dev (requires SERPBASE_API_KEY) for real Google SERP results; that backend applies region but not safesearch. |
region |
string | None | Search region/locale for DDGS backends, and country/language for the SerpBase backend (split on the hyphen into gl/hl). Parallel does not support this control; only the default value is accepted with backend='parallel'. |
safesearch |
string | None | Safe search level for DDGS backends. Parallel and SerpBase do not support this control; only the default value is accepted with those backends. |
verbose |
bool | True | Progress flag. |