# Sequence search API The RNAcentral sequence similarity search API allows you to perform most of the same actions through your own tools as you can through the [web interface](sequence-search.md). Any tool capable of making HTTP requests can communicate with this API, for example `curl`. Base URL: The web interface accepts up to 50 sequences per submission, so use the API for larger batches. ## How it works The API is **asynchronous**: 1. **Submit** a job with `POST /api/submit-job`, passing the `sequence` (10 to 7,000 nucleotides) and an optional list of [expert databases](expert-databases.md) to search, such as `["mirbase"]`. Leave the list empty to search all of RNAcentral. The response contains a `job_id`. 2. **Poll** `GET /api/job-status/` until the `status` is `finished` (or `error` or `not_found`). The response also includes a `progress` percentage. 3. **Retrieve** results from `GET /api/job-results/`, which is paginated with `page` and `page_size` parameters (100 per page by default) and reports the total `hit_count`. Each entry in `entries` includes the `rnacentral_id`, `description`, `e_value`, `identity`, `query_coverage` and `alignment`. Unlike the web interface, which shows the top 1,000 hits, the API returns them all. ## API throttling Job submissions (`/api/submit-job`) are rate limited to **10 requests per minute per IP address**. There is **no rate limit** on job status or results endpoints. When the service is busy, a submission can also be refused with HTTP status `429` and a message asking you to wait. Wait a minute and submit again; the example script below does this automatically. ## Example script An example of a Python script to perform searches for each record of a FASTA file is provided below. It requires Python 3.5 or later and the `biopython` and `requests` packages (`pip install biopython requests`). You can use this script to search for sequences in the RNAcentral database or in one of the [Expert Databases](expert-databases.md). The results will be organized in a new directory. A file in JSON format containing the metadata and the search results will be created. This file will be named with the description of the sequence. Here is an example: ```text results |-- URS00001F7A66_9031 Gallus gallus (chicken) gga-let-7g-5p.json |-- ... ``` ```python """ Usage: python search.py [file] [database] Examples: python search.py file.fasta # search in all databases python search.py file.fasta mirbase # search in miRBase only """ import json import requests import sys import time from Bio import SeqIO from pathlib import Path SERVER = "https://sequence-search.rnacentral.org/" def get_sequence_search_result(description, sequence, job_id): """Poll job status then retrieve all paginated sequence search results.""" job_status = "pending" while True: try: data = requests.get(SERVER + "api/job-status/" + job_id, timeout=30).json() job_status = data["status"] progress = data.get("progress", 0) except requests.exceptions.RequestException as e: print("Error checking job status, retrying: {}".format(e)) time.sleep(10) continue if job_status == "finished": break elif job_status in ("error", "not_found"): print("Search failed for record: {}".format(description)) return { "job_id": job_id, "status": job_status, "description": description, "sequence": str(sequence), } else: print(" {:.0f}% complete...".format(progress)) time.sleep(10) # Fetch results page by page results = [] page = 1 page_size = 100 hit_count = None while True: try: url = "{}api/job-results/{}?page={}&page_size={}".format( SERVER, job_id, page, page_size ) data = requests.get(url, timeout=30).json() except requests.exceptions.RequestException as e: print("Error fetching results page {} for {}: {}".format(page, description, e)) break if hit_count is None: hit_count = data.get("hit_count", 0) entries = data.get("entries", []) results.extend(entries) if not entries or len(results) >= hit_count: break page += 1 return { "job_id": job_id, "hits": hit_count or 0, "status": job_status, "description": description, "sequence": str(sequence), "results": results, } def main(): if len(sys.argv) == 1: print("You must specify the FASTA file") exit() elif len(sys.argv) == 2: filename = sys.argv[1] database = [] elif len(sys.argv) == 3: filename = sys.argv[1] database = [sys.argv[2]] else: print("Usage: python search.py file.fasta [database]") exit() Path("results").mkdir(parents=True, exist_ok=True) with open(filename, mode="r") as handle: for record in SeqIO.parse(handle, "fasta"): description = record.description sequence = record.seq data = {"databases": database, "sequence": str(sequence)} post_job = requests.post(SERVER + "api/submit-job", json=data) while post_job.status_code == 429: print("Rate limited, waiting a minute before resubmitting...") time.sleep(60) post_job = requests.post(SERVER + "api/submit-job", json=data) job_id = None if post_job.status_code == 200: job_id = post_job.json()["job_id"] else: print("Failed to submit job for record:\n{}\n{}".format(description, sequence)) if job_id: result = get_sequence_search_result(description, sequence, job_id) if result: hits = result.get("hits", 0) if hits == 0: print("No results found for {}".format(description)) else: print("Saving {} hit(s) for {}".format(hits, description)) with open("results/" + description + ".json", "w") as f: json.dump(result, f) if __name__ == "__main__": main() ``` ## Results retention Results are kept for **up to 7 days**, after which all data and metadata are deleted. They can be removed sooner when the service is under heavy load, so save the results once a job finishes.