/uniprot/proteins/search

POST /api/uniprot/proteins/search

Price: 20 credits

Search UniProtKB protein entries by text and by organism, gene, keyword and sequence filters

How to use it

Pass `query` for free text or a UniProt query expression, and the named filters for anything structured - they are combined with AND, so a bare filter set needs no `query` at all. `organism_id` matches one taxon exactly while `taxonomy_id` also matches everything below it, which is the difference between human entries and all mammal entries. Rows carry the core annotation only: `features`, `publications` and most of `cross_references` stay empty here, so fetch the accession through uniprot/proteins when those are needed.

Parameters

• access-token string required

Request body

• timeout integer — Max scrapping execution timeout (in seconds) (default: 300; min: 20; max: 1500)
• query string nullable — Free text, or a UniProt query expression such as `kinase AND organism_id:9606` (examples: "insulin", "kinase AND reviewed:true"; minLength: 1)
• accession string nullable — Restrict to one accession (examples: "P05067"; minLength: 1)
• gene string nullable — Gene name or synonym (examples: "INS", "BRCA2"; minLength: 1)
• protein_name string nullable — Words from the protein name (examples: "insulin receptor"; minLength: 1)
• organism_id integer nullable — NCBI taxon id of the organism itself, excluding its descendants (examples: 9606; min: 1)
• taxonomy_id integer nullable — NCBI taxon id matched together with every taxon below it, so 40674 covers all mammals (examples: 40674; min: 1)
• keyword string nullable — UniProt keyword name or KW- identifier (examples: "Kinase", "KW-0418"; minLength: 1)
• proteome string nullable — UniProt proteome identifier (examples: "UP000005640"; minLength: 1)
• ec_number string nullable — Enzyme Commission number (examples: "2.7.11.1"; minLength: 1)
• protein_family string nullable — Protein family name (examples: "serpin"; minLength: 1)
• cross_reference_database string nullable — Keep only entries carrying a cross-reference to this database (examples: "pdb", "alphafolddb"; minLength: 1)
• is_reviewed boolean nullable — True keeps curated Swiss-Prot entries, False keeps unreviewed TrEMBL entries
• protein_existence string nullable — Evidence level for the existence of the protein (one of: "1", "2", "3", "4", "5")
• min_length integer nullable — Shortest sequence to keep, in amino acids (examples: 100; min: 1)
• max_length integer nullable — Longest sequence to keep, in amino acids (examples: 500; min: 1)
• include_isoforms boolean — Also match alternative isoform sequences of an entry (default: false)
• sort string nullable — Result ordering (one of: "accession asc", "accession desc", "annotation_score desc", "annotation_score asc", "gene asc", "gene desc", "length asc", "length desc", "mass asc", "mass desc", "organism_name asc", "organism_name desc", "protein_name asc", "protein_name desc")
• count integer required — Max number of results (min: 1; max: 10000)

Response

• @type string (default: "UniprotProtein")
• accession string required
• secondary_accessions array (default: [])
• entry_name string (default: "")
• is_reviewed boolean (default: false)
• protein_name string (default: "")
• short_names array (default: [])
• alternative_names array (default: [])
• alternative_short_names array (default: [])
• cd_antigen_names array (default: [])
• name_evidences array (default: [])
  • @type string (default: "UniprotEvidence")
  • code string (default: "")
  • source string (default: "")
  • source_id string (default: "")
• ec_numbers array (default: [])
• processed_products array (default: [])
  • @type string (default: "UniprotProcessedProduct")
  • name string (default: "")
  • short_names array (default: [])
  • alternative_names array (default: [])
  • alternative_short_names array (default: [])
  • ec_numbers array (default: [])
• included_domains array (default: [])
  • @type string (default: "UniprotProcessedProduct")
  • name string (default: "")
  • short_names array (default: [])
  • alternative_names array (default: [])
  • alternative_short_names array (default: [])
  • ec_numbers array (default: [])
• sequence_flag string (default: "")
• genes array (default: [])
  • @type string (default: "UniprotGene")
  • name string (default: "")
  • synonyms array (default: [])
  • ordered_locus_names array (default: [])
  • orf_names array (default: [])
  • evidences array (default: [])
    • @type string (default: "UniprotEvidence")
    • code string (default: "")
    • source string (default: "")
    • source_id string (default: "")
• organism object nullable
  • @type string (default: "UniprotOrganism")
  • taxon_id integer nullable
  • scientific_name string (default: "")
  • common_name string (default: "")
  • synonyms array (default: [])
  • lineage array (default: [])
  • evidences array (default: [])
    • @type string (default: "UniprotEvidence")
    • code string (default: "")
    • source string (default: "")
    • source_id string (default: "")
• organism_lineage array (default: [])
  • @type string (default: "UniprotTaxonNode")
  • taxon_id integer nullable
  • scientific_name string (default: "")
  • common_name string (default: "")
  • mnemonic string (default: "")
  • rank string (default: "")
  • synonyms array (default: [])
  • is_hidden boolean nullable
• virus_hosts array (default: [])
  • @type string (default: "UniprotOrganism")
  • taxon_id integer nullable
  • scientific_name string (default: "")
  • common_name string (default: "")
  • synonyms array (default: [])
  • lineage array (default: [])
  • evidences array (default: [])
    • @type string (default: "UniprotEvidence")
    • code string (default: "")
    • source string (default: "")
    • source_id string (default: "")
• gene_locations array (default: [])
  • @type string (default: "UniprotGeneLocation")
  • encoding_type string (default: "")
  • name string (default: "")
  • evidences array (default: [])
    • @type string (default: "UniprotEvidence")
    • code string (default: "")
    • source string (default: "")
    • source_id string (default: "")
• protein_existence string (default: "")
• annotation_score number nullable
• sequence object nullable
  • @type string (default: "UniprotSequence")
  • value string (default: "")
  • length integer nullable
  • mass integer nullable
  • crc64 string (default: "")
  • md5 string (default: "")
• keywords array (default: [])
  • @type string (default: "UniprotKeyword")
  • id string (default: "")
  • name string (default: "")
  • category string (default: "")
  • evidences array (default: [])
    • @type string (default: "UniprotEvidence")
    • code string (default: "")
    • source string (default: "")
    • source_id string (default: "")
• comments array (default: [])
  • @type string (default: "UniprotComment")
  • comment_type string (default: "")
  • molecule string (default: "")
  • texts array (default: [])
  • note string (default: "")
  • subcellular_locations array (default: [])
    • @type string (default: "UniprotSubcellularLocation")
    • location string (default: "")
    • location_id string (default: "")
    • topology string (default: "")
    • topology_id string (default: "")
    • orientation string (default: "")
    • orientation_id string (default: "")
  • disease object nullable
    • @type string (default: "UniprotDisease")
    • name string (default: "")
    • accession string (default: "")
    • acronym string (default: "")
    • description string (default: "")
    • cross_reference_database string (default: "")
    • cross_reference_id string (default: "")
  • isoforms array (default: [])
    • @type string (default: "UniprotIsoform")
    • name string (default: "")
    • synonyms array (default: [])
    • isoform_ids array (default: [])
    • sequence_ids array (default: [])
    • sequence_status string (default: "")
    • note string (default: "")
  • events array (default: [])
  • interactions array (default: [])
    • @type string (default: "UniprotInteraction")
    • interactant object nullable (see schema UniprotInteractant)
    • partner object nullable (see schema UniprotInteractant)
    • experiment_count integer nullable
    • is_cross_organism boolean nullable
  • cofactors array (default: [])
    • @type string (default: "UniprotCofactor")
    • name string (default: "")
    • cross_reference string (default: "")
  • reaction object nullable
    • @type string (default: "UniprotReaction")
    • name string (default: "")
    • ec_number string (default: "")
    • cross_references array (default: [])
  • physiological_reactions array (default: [])
    • @type string (default: "UniprotPhysiologicalReaction")
    • direction string (default: "")
    • cross_reference string (default: "")
  • kinetic_constants array (default: [])
    • @type string (default: "UniprotKineticConstant")
    • constant number nullable
    • unit string (default: "")
    • substrate string (default: "")
  • kinetic_note string (default: "")
  • absorption object nullable
    • @type string (default: "UniprotAbsorption")
    • max number nullable
    • is_approximate boolean nullable
    • note string (default: "")
  • resource_name string (default: "")
  • resource_url string (default: "")
  • is_ftp boolean nullable
  • mass_spectrometry_method string (default: "")
  • mass number nullable
  • mass_error number nullable
  • sequence_caution_type string (default: "")
  • sequence_caution_id string (default: "")
  • edited_location_type string (default: "")
  • edited_positions array (default: [])
  • evidences array (default: [])
    • @type string (default: "UniprotEvidence")
    • code string (default: "")
    • source string (default: "")
    • source_id string (default: "")
• features array (default: [])
  • @type string (default: "UniprotFeature")
  • feature_type string (default: "")
  • description string (default: "")
  • feature_id string (default: "")
  • start integer nullable
  • end integer nullable
  • start_modifier string (default: "")
  • end_modifier string (default: "")
  • location_sequence string (default: "")
  • original_sequence string (default: "")
  • alternative_sequences array (default: [])
  • ligand_name string (default: "")
  • ligand_id string (default: "")
  • ligand_label string (default: "")
  • ligand_note string (default: "")
  • ligand_part_name string (default: "")
  • ligand_part_id string (default: "")
  • cross_references array (default: [])
  • evidences array (default: [])
    • @type string (default: "UniprotEvidence")
    • code string (default: "")
    • source string (default: "")
    • source_id string (default: "")
• publications array (default: [])
  • @type string (default: "UniprotPublication")
  • number integer nullable
  • citation_id string (default: "")
  • citation_type string (default: "")
  • citation_title string (default: "")
  • authors array (default: [])
  • authoring_group array (default: [])
  • editors array (default: [])
  • journal string (default: "")
  • book_name string (default: "")
  • publisher string (default: "")
  • address string (default: "")
  • patent_number string (default: "")
  • submission_database string (default: "")
  • publication_date string (default: "")
  • volume string (default: "")
  • first_page string (default: "")
  • last_page string (default: "")
  • pubmed_id string (default: "")
  • doi string (default: "")
  • positions array (default: [])
  • source_comments array (default: [])
  • evidences array (default: [])
    • @type string (default: "UniprotEvidence")
    • code string (default: "")
    • source string (default: "")
    • source_id string (default: "")
• cross_references array (default: [])
  • @type string (default: "UniprotCrossReference")
  • database string (default: "")
  • database_id string (default: "")
  • isoform_id string (default: "")
  • attributes object (default: {})
    • * string
  • evidences array (default: [])
    • @type string (default: "UniprotEvidence")
    • code string (default: "")
    • source string (default: "")
    • source_id string (default: "")
• comment_counts object (default: {})
  • * integer
• feature_counts object (default: {})
  • * integer
• uniparc_id string (default: "")
• first_public_date string (default: "")
• last_annotation_update_date string (default: "")
• last_sequence_update_date string (default: "")
• entry_version integer nullable
• sequence_version integer nullable
• url string (default: "")

Errors

• 422 — The request body did not validate Check the fields against this schema. A URN with the wrong prefix is the most common cause.
• 408 — The request ran past its time limit Raise `timeout` in the request body, up to the maximum this endpoint documents. Lowering `count` or turning off the `with_*` flags also helps, because less work finishes sooner.
• 412 — The entity was not found, or a precondition failed Retrying will not help: either the entity does not exist, or the input points at a different one.
• 429 — Too many requests: a rate limit or a usage window is exhausted When the response carries an X-Retry-After header, wait that many seconds and retry: the same number is in the body as `detail.retry_after`, and the limit clears once that window passes. The message in the body names the limit that was hit.
• 500 — Something broke on our side Retrying will not help. If it keeps happening, send us the X-Request-ID from the response headers.
• 529 — Rate limit reached, or the endpoint is overloaded Wait at least 30 seconds, then retry.

Response headers

• X-Error — Error message text (present only on error)
• X-Request-ID — Unique request identifier
• X-Execution-Time — Execution time in seconds
• X-Result-Count — How many records the body carries. 0 means an empty result, which is a normal answer and not by itself an error. A non-zero count can come back together with X-Error when the failure happened partway through — read this header and X-Error independently.
• X-Total-Available-Results — How many records exist for this query, when the endpoint can say. On a `dry_run` request this is the answer and the body is empty. It saturates: the endpoint's documented maximum means 'at least that many', any smaller number is exact.
• X-Warning — Present when the request body carried keys this endpoint does not document. They were ignored, so any filter you meant to apply through them did not apply. Check the spelling against this schema and retry.
• X-Retry-After — Seconds to wait before retrying. Present only on 429.