# Uniprot Protein Scraper (`zerobreak/uniprot-protein-scraper`) Actor

UniProt Protein Scraper is a Python tool designed to automatically extract protein sequences, functional annotations, taxonomic data, and cross-references from the UniProt database, saving them into structured formats for bioinformatics research.

- **URL**: https://apify.com/zerobreak/uniprot-protein-scraper.md
- **Developed by:** [ZeroBreak](https://apify.com/zerobreak) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.99 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## UniProt Protein Scraper: Protein Entry Search

<p align="center">
  <img src="https://imgur.com/ZoeJSvI.png" alt="UniProt Protein Scraper" width="800" />
</p>

Search protein records using the public UniProt REST API. Retrieve protein information through keyword-based queries or look up specific records by accession number, then export results as JSON, CSV, or Excel.

No login or API key is required. The scraper supports paginated searches, duplicate-accession detection, request retries, and structured error reporting so that individual failures do not stop the entire run.

### Features

- Search UniProtKB records using UniProt query syntax.
- Retrieve individual protein entries using accession numbers.
- Extract protein names, organism information, gene names, sequence lengths, and additional annotations.
- Select specific fields for search results.
- Follow pagination to collect multiple pages of results.
- Remove duplicate protein accessions.
- Handle request timeouts, rate limits, and server errors.
- Record failed inputs in structured error rows.
- Schedule recurring runs to monitor protein annotation updates.
- Export datasets as JSON, CSV, or Excel through the Apify interface.

### Use Cases

- **Protein research:** Search for insulin, specific genes, or organisms and collect matching UniProtKB records.
- **Accession lookup:** Retrieve protein records using known accession numbers, such as `P01308`.
- **Annotation updates:** Schedule periodic exports containing protein names, organisms, gene names, and sequence lengths.
- **Research pipelines:** Export structured data for analysis with Python, Pandas, Jupyter notebooks, and scientific tools.
- **Data validation:** Check whether a search returns reviewed Swiss-Prot records before running a larger collection task.

### Input Parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `mode` | string | `search` | Select `search` to query UniProtKB or `entry` to retrieve individual records by accession. |
| `query` | string | `insulin` | UniProt query syntax used in search mode. |
| `accessions` | array | `P01308` | Protein accession numbers used in entry mode, with one accession per item. |
| `fields` | string | `accession,protein_name,organism_name,length,gene_names` | Comma-separated list of fields returned by search mode. |
| `maxItems` | integer | `100` | Maximum number of saved protein records. Allowed range: 1–1,000. |
| `timeoutSecs` | integer | `300` | Maximum total runtime in seconds, up to 3,600. |
| `requestTimeoutSecs` | integer | `30` | Maximum wait time for an individual HTTP request, in seconds. |

### Example Input

#### Search Protein Records

```json id="uniprotsearch1"
{
  "mode": "search",
  "query": "insulin",
  "fields": "accession,protein_name,organism_name,length,gene_names",
  "maxItems": 100,
  "timeoutSecs": 300,
  "requestTimeoutSecs": 30
}
```

#### Retrieve a Specific Protein Entry

Set `mode` to `entry` and provide one or more accession numbers in the `accessions` array.

```json id="uniprotentry1"
{
  "mode": "entry",
  "accessions": [
    "P01308"
  ],
  "maxItems": 100,
  "timeoutSecs": 300,
  "requestTimeoutSecs": 30
}
```

### What Data Does This Scraper Extract?

Each protein record is saved as a separate dataset item. Failed inputs are recorded in separate error rows containing the relevant error and input information. The scraper continues processing other records whenever possible.

#### Example Output

```json id="uniprotoutput1"
{
  "entryType": "UniProtKB reviewed (Swiss-Prot)",
  "primaryAccession": "P01308",
  "organism": {
    "scientificName": "Homo sapiens",
    "commonName": "Human",
    "taxonId": 9606
  },
  "proteinDescription": {
    "recommendedName": {
      "fullName": {
        "value": "Insulin"
      }
    },
    "flag": "Precursor"
  },
  "genes": [
    {
      "geneName": {
        "value": "INS"
      }
    }
  ],
  "sequence": {
    "length": 110
  },
  "extraAttributes": {
    "uniParcId": "UPI00000017EA"
  },
  "sourceUrl": "API_REQUEST_URL",
  "scrapedAt": "2026-10-12T00:00:00+00:00"
}
```

The example uses a placeholder for the request URL. Actual output may contain additional information depending on the record and the API response.

### Output Fields

| Field | Type | Description |
|---|---|---|
| `entryType` | string | UniProt entry classification supplied by the source. |
| `primaryAccession` | string | Primary protein accession number. Duplicate accessions are removed. |
| `organism` | object | Scientific name, common name, taxonomic ID, and lineage when available. |
| `proteinDescription` | object | Recommended protein name and chain information when available. |
| `genes` | array | Gene names associated with the protein entry. |
| `sequence` | object | Sequence information, including length in search results. |
| `extraAttributes` | object | Additional attributes, such as the UniParc identifier, when available. |
| `sourceUrl` | string | Request URL associated with the returned record. |
| `scrapedAt` | string | UTC timestamp indicating when the record was saved. |
| `error` | string | Error description, included only in error rows. |
| `input` | string | Query, accession number, or other input associated with an error row. |

Search responses are limited to the configured fields. Full entry responses can be large, so the scraper retains the same core dataset structure when processing individual accessions.

### How It Works

1. **Validate inputs:** Read the parameters and validate the configured limits.
2. **Send API requests:** Query the public UniProt REST API using a descriptive User-Agent.
3. **Search records:** In search mode, request JSON results using the selected fields and a page size of up to 500 records.
4. **Follow pagination:** Continue through available pages until the item limit, runtime limit, or final page is reached.
5. **Retrieve individual entries:** In entry mode, retrieve each valid accession once. Invalid accessions are recorded as error rows.
6. **Retry failed requests:** Retry HTTP 429 responses, HTTP 5xx errors, and timeouts up to three additional times, using backoff delays of 2, 4, and 8 seconds. Respect longer server-provided retry delays where applicable.
7. **Control request rate:** Maintain an approximate rate of three requests per second.
8. **Remove duplicates:** Skip duplicate `primaryAccession` values and save collected records to the dataset.

### Limits and Data Usage

- **Authentication:** No API key or login is required.
- **Maximum records:** Up to 1,000 saved protein records per run.
- **Default records:** 100.
- **Search pagination:** Up to 500 records per request.
- **Request rate:** Approximately three requests per second, with retries when the service indicates that requests should be slowed down.
- **Licensing:** UniProt data is available under the CC BY 4.0 license, subject to the applicable data and attribution terms.

When redistributing data, provide appropriate attribution and follow the applicable licensing requirements.

### Frequently Asked Questions

#### Does UniProt Protein Scraper require an API key?

No. The public UniProt REST API can be accessed without an API key.

#### How many protein records can one run save?

The default limit is 100 records, and the maximum is 1,000. Select only the fields you need to reduce unnecessary data and improve processing efficiency.

#### What is the difference between search and entry mode?

**Search mode** accepts UniProt query syntax and retrieves matching records using the selected fields.

**Entry mode** retrieves individual protein records using their accession numbers and retains the same core dataset structure.

#### Why did I receive an error row instead of a protein record?

An empty query, invalid accession, non-JSON response, or final HTTP error may produce an error row containing the error description and original input. Other records can still be saved during the same run.

#### Can I export the results to CSV, JSON, and Excel?

Yes. The resulting dataset can be exported in JSON, CSV, or Excel format for further analysis, reporting, or integration with other data-processing workflows.

#### Can I schedule recurring protein searches?

Yes. Schedule recurring runs to refresh protein metadata and compare records across collection periods.

### Pricing

The actor is free to run. Apify platform usage is subject to the applicable Apify plan and usage charges.

### Trademark Notice

UniProt and related names, logos, and trademarks belong to their respective owners. Their use in this documentation is solely for identifying the data source and does not imply affiliation, sponsorship, endorsement, or partnership.

### Disclaimer

This actor is an independent tool and is not affiliated with, endorsed by, sponsored by, or officially associated with UniProt or its owners.

Data is collected from publicly accessible sources. Users are responsible for complying with applicable source terms, rate limits, licensing requirements, and attribution obligations.

### Is Web Scraping Legal?

Collecting publicly available data through a public API may be permitted, but the legality and conditions of use depend on the data, applicable laws, licensing terms, and intended purpose.

- **Personal data:** If collected records contain personal information, applicable privacy laws may impose additional obligations. Collect and retain such information only when there is a legitimate and lawful basis.
- **Copyright and licensing:** Protein records and associated annotations may be subject to specific licensing terms. Follow the applicable license and attribution requirements when redistributing data.
- **Terms of use:** Respect the source's usage policies, request limits, and applicable data-use requirements.
- **Legal advice:** This information is provided for general educational purposes and does not constitute legal advice. Consult a qualified professional if you need advice about a specific use case.

# Actor input Schema

## `mode` (type: `string`):

search calls the UniProtKB search endpoint. entry fetches one full JSON record per accession.

## `query` (type: `string`):

UniProt query syntax used in search mode, for example insulin or gene:INS AND organism_id:9606.

## `accessions` (type: `array`):

UniProt accessions to fetch in entry mode, one per line, such as P01308.

## `fields` (type: `string`):

Comma-separated UniProt return fields for search mode. Entry mode always returns the stored record fields.

## `maxItems` (type: `integer`):

Maximum protein records to save. Values are clamped between 1 and 1000.

## `timeoutSecs` (type: `integer`):

Stop fetching when this many seconds have elapsed. Default 300, maximum 3600.

## `requestTimeoutSecs` (type: `integer`):

Per-request HTTP timeout in seconds. Default 30.

## `proxyConfiguration` (type: `object`):

Optional proxy for UniProt requests. Leave useApifyProxy false to call the public API directly.

## Actor input object example

```json
{
  "mode": "search",
  "query": "insulin",
  "accessions": [
    "P01308"
  ],
  "fields": "accession,protein_name,organism_name,length,gene_names",
  "maxItems": 100,
  "timeoutSecs": 300,
  "requestTimeoutSecs": 30,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `datasetUrl` (type: `string`):

Default dataset with protein records and any error rows.

## `overviewUrl` (type: `string`):

Table view of protein entries.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "query": "insulin",
    "accessions": [
        "P01308"
    ],
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("zerobreak/uniprot-protein-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "query": "insulin",
    "accessions": ["P01308"],
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("zerobreak/uniprot-protein-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "query": "insulin",
  "accessions": [
    "P01308"
  ],
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call zerobreak/uniprot-protein-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,zerobreak/uniprot-protein-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/W7pvhyAFNi6f9GJnB/builds/XWletNrnA9IoHjomw/openapi.json