Nih APIblast.ncbi.nlm.nih.gov ↗
Submit DNA and protein sequences to NCBI BLAST and retrieve structured JSON alignment results. Supports blastn, blastp, blastx, tblastn, and tblastx.
What is the Nih API?
This API exposes 4 endpoints for running sequence similarity searches against NCBI's biological databases and retrieving structured alignment results. Use submit_blast to queue a job and get a Request ID, check_status to poll its progress, and get_results to fetch the final BlastOutput2 alignment report — or use search_blast to handle all three steps in a single blocking call.
curl -X POST 'https://api.parse.bot/scraper/1393a460-4f8b-4db5-8c26-8ad893041880/submit_blast' \
-H 'X-API-Key: $PARSE_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"query": "ATGATGATGATGATGATG",
"program": "blastn",
"database": "nt",
"genetic_code": "1"
}'Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace blast-ncbi-nlm-nih-gov-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: NCBI BLAST API — submit jobs, check status, retrieve results."""
from parse_apis.ncbi_blast_api import Blast, BlastProgram, JobNotFound
client = Blast()
# Submit a nucleotide BLAST job and get the tracking RID back immediately.
job = client.jobs.submit(query="ATGATGATGATGATGATG", program=BlastProgram.BLASTN, database="nt")
print(f"Submitted job: RID={job.rid}, estimated wait={job.rtoe}s")
# Check the job's processing status (WAITING, SEARCHING, READY, FAILED, UNKNOWN).
job_status = job.status()
print(f"Job status: {job_status.status}")
# Once READY, retrieve the full alignment results.
try:
result = job.results()
for report in result.BlastOutput2:
print(f"Program: {report.program}, Version: {report.version}")
except JobNotFound as exc:
print(f"Job not found: {exc.rid}")
# Or use search() for a single blocking call that submits + polls + returns results.
result = client.jobs.search(query="GCTAGCTAGCTAGCTAGCTA", program=BlastProgram.BLASTN, database="nt")
for report in result.BlastOutput2:
print(f"Search result — program: {report.program}, version: {report.version}")
print("Exercised: jobs.submit / job.status / job.results / jobs.search")
Submit a BLAST job to NCBI and receive a Request ID (RID) for tracking. The RID can be used with check_status and get_results endpoints to monitor and retrieve results. Returns immediately with the RID and an estimated time of execution (RTOE) in seconds.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Nucleotide or protein sequence to search (raw sequence or FASTA format). |
| program | string | BLAST program to use. |
| database | string | Target database. Common values: nt (nucleotide collection), nr (non-redundant protein). If omitted, defaults to nt for blastn or nr for other programs. |
| genetic_code | string | NCBI genetic code number for translation (used by blastx/tblastx). Standard code is 1. |
{
"type": "object",
"fields": {
"rid": "string, the Request ID for tracking this BLAST job",
"rtoe": "integer, estimated time of execution in seconds"
},
"sample": {
"data": {
"rid": "2M9SBYDG014",
"rtoe": 30
},
"status": "success"
}
}About the Nih API
Submitting and Tracking BLAST Jobs
The submit_blast endpoint accepts a nucleotide or protein sequence (raw or FASTA format) along with three optional parameters: program (blastn, blastp, blastx, tblastn, or tblastx), database (e.g. nt for nucleotide or nr for protein), and genetic_code for translation-based searches like blastx or tblastx. The response returns an rid (Request ID) and an rtoe integer estimating how many seconds the job will take. The RID is then passed to check_status, which returns one of five status strings: WAITING, SEARCHING, READY, FAILED, or UNKNOWN.
Retrieving Alignment Results
Once check_status returns READY, get_results accepts the same rid and returns the full BLAST report as a BlastOutput2 array. Each element in the array contains the program name, search parameters, and a nested structure of hits with alignment statistics. If the job is still processing when get_results is called, the response returns an upstream_error with HTTP status 202.
Single-Call Search with search_blast
The search_blast endpoint accepts the same inputs as submit_blast but internally handles polling and returns the completed BlastOutput2 result directly. Because BLAST jobs can take anywhere from a few seconds to several minutes depending on sequence length, database size, and NCBI server load, this endpoint may have a long response time. It is best suited for synchronous workflows where a single blocking call is acceptable.
Database and Program Selection
If database is omitted, the API defaults to nt when program is blastn and to nr for protein-mode programs. The genetic_code parameter is relevant only when the query sequence requires translation (blastx, tblastx) and corresponds to standard NCBI genetic code table numbers.
The Nih API is a managed, monitored endpoint for blast.ncbi.nlm.nih.gov — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when blast.ncbi.nlm.nih.gov changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official blast.ncbi.nlm.nih.gov API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Identify the species of an unknown DNA sample by running blastn against the nt database and inspecting hits in BlastOutput2
- Find functionally similar proteins across organisms by submitting an amino acid sequence to blastp against nr
- Translate and search a nucleotide query against a protein database using blastx to find coding regions
- Automate genomic pipeline steps by polling check_status and fetching results with get_results only when status is READY
- Batch-process multiple sequences by submitting them via submit_blast, storing RIDs, and retrieving results asynchronously
- Validate synthetic gene sequences against public databases to detect unintended homology before synthesis
- Support phylogenetic research by collecting alignment statistics and hit descriptions from BlastOutput2 for downstream analysis
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.