Search Compounds
pubchem_search_compoundsRead-onlyIdempotent
Find PubChem compounds by identifier, formula, substructure, superstructure, or similarity. Returns page of CIDs with optional properties.
Instructions
Search PubChem for chemical compounds by identifier (name, SMILES, or InChIKey, batched up to 25), molecular formula in Hill notation, substructure or superstructure containment, or 2D Tanimoto similarity. Returns a page of CIDs — reach matches past maxResults with offset. Optionally hydrate results with properties to avoid a follow-up pubchem_get_compound_details call.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Required for substructure/superstructure/similarity searches. A SMILES string (e.g. "CC(=O)O") or PubChem CID as a string (e.g. "2244"). | |
| offset | No | Zero-based index of the first CID to return. Pass the nextOffset from a previous call to read the following page. Identifier lookups resolve every match up front, so paging them is free; formula, substructure, superstructure, and similarity searches have to ask PubChem for offset + maxResults records to reach a page, so deep pages cost progressively more upstream — hence the 10000 ceiling. Default: 0. | |
| formula | No | Required for formula search. Molecular formula in Hill notation (e.g. "C6H12O6", "CaH2O2"). | |
| queryType | No | Required for structure/similarity searches. Format of the query: "smiles" or "cid". | |
| threshold | No | Similarity search only. Minimum Tanimoto similarity (70-100). 90+ for close analogs, 70-80 for scaffold hops. Default: 90. | |
| maxResults | No | Maximum CIDs to return per page (1-200). Use offset to reach matches past this page. Default: 20. | |
| properties | No | Optional: fetch these properties for each result, avoiding a follow-up details call. E.g. ["MolecularFormula", "MolecularWeight", "CanonicalSMILES"]. | |
| searchType | Yes | Search strategy. "identifier": name/SMILES/InChIKey lookup. "formula": molecular formula. "substructure": find compounds containing the query as a substructure. "superstructure": find compounds that are themselves substructures of the query. "similarity": 2D Tanimoto similarity to the query. | |
| identifiers | No | Required for identifier search. Array of identifiers to resolve (1-25). Examples: ["aspirin", "ibuprofen"] for name, ["CC(=O)OC1=CC=CC=C1C(=O)O"] for SMILES, ["BSYNRYMUTXBXSQ-UHFFFAOYSA-N"] for inchikey (27-char block format). | |
| identifierType | No | Required for identifier search. Type of chemical identifier: "name", "smiles", or "inchikey". | |
| allowOtherElements | No | Formula search only. When true, includes compounds with additional elements beyond the formula. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The maxResults cap that was applied. | |
| shown | No | CIDs returned on this page. | |
| notice | No | Recovery guidance when no compounds matched, when the offset runs past the matches observed, when identifiers failed to resolve, or when further pages remain. Absent when this page is complete and every identifier resolved. | |
| offset | Yes | Zero-based index of the first CID returned. | |
| results | Yes | Matching compounds. | |
| truncated | No | True when matching CIDs remain past this page. | |
| nextOffset | No | Offset to pass on the next call to continue past this page. Omitted when no further matches remain. | |
| searchType | Yes | Search strategy used: identifier, formula, substructure, superstructure, or similarity. | |
| totalFound | No | Exact number of matching CIDs across all pages. Omitted when a formula, substructure, superstructure, or similarity search saturated the records it requested — PubChem returns no match count for those, so totalFoundAtLeast reports a floor instead. | |
| totalFoundAtLeast | No | Lower bound on matching CIDs, reported in place of totalFound when the exact count is unavailable. At least this many match, and the true total may be higher; page further with offset to observe more. | |
| unresolvedIdentifiers | No | Identifier-mode only: input identifiers that resolved to no CID. Omitted when every identifier resolved and for non-identifier searches. |