# ICD-10 Codes Search & Export (`automation-lab/icd10-code-search-export`) Actor

Search ICD-10-CM codes by diagnosis text or code and export normalized records for medical coding lookup and healthcare data normalization.

- **URL**: https://apify.com/automation-lab/icd10-code-search-export.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.92 / 1,000 icd-code extracteds

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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## ICD-10 Codes Search & Export

Search official **ICD-10 codes** by diagnosis text, symptom, exact code, or code prefix, then export normalized ICD-10-CM records to JSON, CSV, Excel, or your data pipeline.

The Actor queries the public [NLM Clinical Tables ICD-10-CM service](https://clinicaltables.nlm.nih.gov/) directly. It returns the code and official diagnosis title supplied by NLM, adds normalization-friendly fields, and preserves the query and source URL behind every match.

### What does this Actor do?

Use the Actor to:

- look up ICD-10-CM codes for diagnosis text such as `depression`;
- search an exact code such as `F32.A`;
- export a code family such as `E11` for type 2 diabetes;
- combine several medical coding lookups in one run;
- deduplicate overlapping matches by code;
- normalize dotted and compact code forms for database joins;
- attach chapter, parent-category, rank, and source metadata;
- feed structured records to spreadsheets, warehouses, EHR support tools, or terminology workflows.

This is a search-and-export utility, not a bulk mirror of every annual CMS release.

### Who is it for?

- **Medical coding teams** doing fast diagnosis-to-code research.
- **Healthcare data engineers** normalizing code fields across systems.
- **Revenue-cycle analysts** preparing reference tables for review.
- **Terminology managers** building bounded code lists for downstream tools.
- **Researchers** who need reproducible query context and source links.
- **Automation builders** connecting ICD-10-CM lookup to Apify Tasks, schedules, webhooks, or APIs.

The output can support research and normalization. It does not replace the judgment of a qualified coder or clinician.

### Why use it?

#### Official structured source

The Actor uses NLM Clinical Tables rather than scraping third-party diagnosis pages.

#### Search by text or code

The same `queries` input accepts terms such as `anxiety`, exact codes such as `F32.A`, and prefixes such as `E11`.

#### Normalized output

Each item includes dotted and compact code forms, the matching query, rank, total match count, and source provenance.

#### Honest metadata

NLM exposes `code` and `name`. Chapter and parent fields are conservatively derived from code structure. Billable status remains `null` rather than being guessed.

#### Bounded, predictable runs

Control matches per query, total records, and cross-query deduplication. Requests have bounded retries and timeouts.

### Input parameters

| Field | Type | Default | Description |
|---|---:|---:|---|
| `queries` | string array | `depression`, `diabetes` | One to 20 diagnosis terms, exact codes, or prefixes. |
| `maxResultsPerQuery` | integer | `20` | Maximum matches requested per query, from 1 to 500. |
| `maxItems` | integer | `20` | Maximum total dataset records, from 1 to 5,000. |
| `deduplicateCodes` | boolean | `true` | Keep only the first occurrence of a code across queries. |

Empty query arrays and more than 20 queries fail with a clear input error.

### Getting started

1. Open the Actor in Apify Console.
2. Add one or more diagnosis terms or ICD-10-CM codes to **Diagnosis text or codes**.
3. Choose the per-query and total output limits.
4. Keep **Deduplicate codes** enabled for a normalized code list.
5. Click **Start**.
6. Open the **Dataset** tab.
7. Export the result as JSON, CSV, Excel, XML, or RSS, or consume it through the API.

A useful first input is:

```json
{
  "queries": ["depression", "anxiety"],
  "maxResultsPerQuery": 50,
  "maxItems": 100,
  "deduplicateCodes": true
}
```

### ICD-10 codes lookup examples

#### Find ICD-10 codes for depression

```json
{
  "queries": ["depression"],
  "maxResultsPerQuery": 25,
  "maxItems": 25,
  "deduplicateCodes": true
}
```

This currently returns records including `F32.A — Depression, unspecified`.

#### Export the E11 code family

```json
{
  "queries": ["E11"],
  "maxResultsPerQuery": 100,
  "maxItems": 100,
  "deduplicateCodes": true
}
```

Use prefix lookups to build a bounded source-backed code family export.

#### Normalize several mental-health lookups

```json
{
  "queries": ["depression", "anxiety", "post-traumatic stress"],
  "maxResultsPerQuery": 100,
  "maxItems": 250,
  "deduplicateCodes": true
}
```

This exercises multi-query lookup and removes repeated codes from the final dataset.

### Output fields

| Field | Meaning |
|---|---|
| `query` | Input term that produced the result. |
| `code` | Official dotted ICD-10-CM code returned by NLM. |
| `compactCode` | Code with the dot removed for normalization and joins. |
| `title` | Official diagnosis title returned by NLM. |
| `rank` | One-based rank within the query response. |
| `totalMatchesForQuery` | Total matches reported by NLM. |
| `chapter` | Chapter label derived from the code range. |
| `chapterRange` | Range used to derive the chapter. |
| `parentCode` | Three-character category for dotted codes, otherwise `null`. |
| `billable` | Always `null`; the source does not expose authoritative billable status. |
| `metadataNote` | Disclosure of source and derived metadata boundaries. |
| `source` | `NLM Clinical Tables ICD-10-CM`. |
| `sourceUrl` | Exact API request URL for provenance. |
| `retrievedAt` | UTC timestamp when the response was normalized. |

### Example output

```json
{
  "query": "depression",
  "code": "F32.A",
  "compactCode": "F32A",
  "title": "Depression, unspecified",
  "rank": 1,
  "totalMatchesForQuery": 5,
  "chapter": "Mental, behavioral and neurodevelopmental disorders",
  "chapterRange": "F01-F99",
  "parentCode": "F32",
  "billable": null,
  "metadataNote": "NLM exposes code and title only; hierarchy is derived from the code and billable status is not asserted.",
  "source": "NLM Clinical Tables ICD-10-CM",
  "sourceUrl": "https://clinicaltables.nlm.nih.gov/api/icd10cm/v3/search?terms=depression&sf=code%2Cname&df=code%2Cname&maxList=25",
  "retrievedAt": "2026-08-28T06:30:00.000Z"
}
```

### How much does it cost to search ICD-10 codes?

Pay-per-event pricing has two events:

- **Lookup started:** `$0.005` once per run.
- **ICD-10-CM code:** charged once per saved record using volume tiers.

Current per-code prices are `$0.0075164` (FREE), `$0.006536` (BRONZE), `$0.0050981` (SILVER), `$0.0039216` (GOLD), `$0.0026144` (PLATINUM), and `$0.0018301` (DIAMOND).

Examples at the FREE tier, including the start fee:

| Saved codes | Estimated charge |
|---:|---:|
| 1 | `$0.0125164` |
| 25 | `$0.19291` |
| 100 | `$0.75664` |

You are charged for saved records, not zero-result matches or rejected duplicate rows. Platform compute usage may also apply under your Apify plan.

### Export and integration patterns

#### Spreadsheet reference list

Run an exact prefix lookup, open the default dataset, and export it as Excel or CSV.

#### Database normalization

Join `compactCode` against systems that omit dots while retaining `code` for display.

#### Scheduled reference checks

Save the input as an Apify Task, schedule it, and compare successive datasets in your own workflow. The Actor does not itself calculate release diffs or send alerts.

#### Webhook pipeline

Attach a run-succeeded webhook to send the dataset ID to an ETL job, queue, or serverless function.

### Run through the Apify API with cURL

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~icd10-code-search-export/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": ["depression"],
    "maxResultsPerQuery": 25,
    "maxItems": 25,
    "deduplicateCodes": true
  }'
```

To wait for completion and return dataset items, use the synchronous dataset-items endpoint documented in the Apify API reference.

### Run with JavaScript

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/icd10-code-search-export').call({
    queries: ['E11'],
    maxResultsPerQuery: 100,
    maxItems: 100,
    deduplicateCodes: true,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### Run with Python

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/icd10-code-search-export').call(run_input={
    'queries': ['depression', 'anxiety'],
    'maxResultsPerQuery': 50,
    'maxItems': 100,
    'deduplicateCodes': True,
})
items = client.dataset(run['defaultDatasetId']).list_items().items
print(items)
```

### Use with MCP and AI assistants

#### Claude Code setup

Add the Actor to Claude Code:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/icd10-code-search-export"
```

#### Claude Desktop, Cursor, and VS Code setup

Use this HTTP MCP configuration in Claude Desktop, Cursor, or VS Code:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/icd10-code-search-export"
    }
  }
}
```

Example prompts:

- “Search ICD-10-CM for depression and return the top 10 code records.”
- “Export up to 100 codes beginning with E11 as a table.”
- “Look up anxiety and post-traumatic stress, deduplicate codes, and summarize the chapters.”

AI-generated coding interpretations should be reviewed by a qualified professional.

### Limits and source behavior

- The Actor searches US ICD-10-CM data exposed by NLM Clinical Tables.
- It does not search ICD-10-PCS, ICD-9, procedure codes, or non-US clinical modifications.
- NLM limits a query response to 500 displayed matches.
- The reported total may exceed the returned rows.
- `billable` is intentionally `null` because the API does not expose that fact.
- Chapter and parent fields are derived; they are not additional NLM response fields.
- Inclusion terms, exclusions, code notes, and authoritative related-code links are not exposed by this source and are not fabricated.
- Naturally valid queries can return no records.
- Upstream rate limits, errors, or timeouts fail after three bounded attempts.
- The Actor uses direct HTTPS and does not require a proxy, browser, login, or cookies.

### Tips for reliable results

- Use a specific phrase rather than a full clinical note.
- Use a code prefix when you need a family of related codes.
- Increase `maxResultsPerQuery` only when the query is broad.
- Set `maxItems` below the sum of per-query limits to cap total output.
- Keep deduplication enabled for reference tables.
- Disable deduplication when query-level overlap is analytically meaningful.
- Store your exact input with the dataset for reproducible research.

### Legality and responsible use

The source is a public US government-supported clinical terminology service. Use the data in accordance with source terms, applicable laws, organizational policies, and professional coding requirements.

This Actor does not provide medical advice, diagnosis, reimbursement guarantees, or an authoritative billing determination. Verify codes, effective dates, payer rules, and billable specificity with current official resources and qualified professionals before operational use.

Do not send patient names, identifiers, clinical notes containing protected health information, or other sensitive personal data as search terms.

### Troubleshooting

#### Why did my query return no records?

Check spelling, try a shorter diagnosis phrase, or search a code prefix. A successful zero-result run is possible when NLM has no matching code or title.

#### Why did I receive fewer records than `maxItems`?

`maxItems` is a ceiling, not a promised count. NLM may have fewer matches, per-query limits may be lower, and deduplication can remove overlapping codes.

#### Why is `billable` null?

The NLM search API documents only code and name fields. The Actor does not infer an authoritative billing flag from code length.

#### Why did the run fail after retries?

NLM may be temporarily unavailable or rate-limiting requests. Retry later with fewer or more specific terms. The Actor reports the affected query and upstream status.

### FAQ

#### Is this an ICD-10 codes list?

It creates a bounded list from one or more searches. It is not a complete annual-release download.

#### Can I search several diagnoses at once?

Yes. Supply up to 20 entries in `queries` and set the overall `maxItems` limit.

#### Does it preserve which diagnosis matched each code?

Yes. Every row includes `query`. With deduplication enabled, the first query that produced a repeated code is retained.

#### Can I export to Excel?

Yes. Use the dataset Export button and choose Excel, CSV, JSON, XML, or another supported format.

#### Does it need a proxy?

No. It calls the anonymous public NLM API directly.

#### Does it replace professional coding software?

No. It is a lookup and normalization utility whose output requires appropriate professional review.

### Related automation-lab Actors

- [ClinicalTrials.gov Study Scraper](https://apify.com/automation-lab/clinicaltrials-gov-study-scraper) for structured clinical-study records.

Keep separate datasets for terminology lookup and clinical-study extraction, then join them only when your workflow has a valid analytical basis.

### Support

If a reproducible input fails, include the Actor run URL, sanitized input, expected behavior, and observed behavior in an Apify issue. Do not include patient or credential data.

# Actor input Schema

## `queries` (type: `array`):

One to 20 search terms. Use diagnosis text such as depression or diabetes, an exact code such as F32.A, or a code prefix such as E11.

## `maxResultsPerQuery` (type: `integer`):

Maximum matches requested from NLM for each search term. NLM supports up to 500.

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

Stop after this many normalized dataset records across all queries.

## `deduplicateCodes` (type: `boolean`):

Save a code only once when it matches more than one supplied query. The first matching query is retained.

## Actor input object example

```json
{
  "queries": [
    "depression",
    "diabetes"
  ],
  "maxResultsPerQuery": 20,
  "maxItems": 20,
  "deduplicateCodes": true
}
```

# Actor output Schema

## `dataset` (type: `string`):

Normalized code, title, hierarchy, query context, and source metadata.

# 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 = {
    "queries": [
        "depression",
        "diabetes"
    ],
    "maxResultsPerQuery": 20,
    "maxItems": 20,
    "deduplicateCodes": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/icd10-code-search-export").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 = {
    "queries": [
        "depression",
        "diabetes",
    ],
    "maxResultsPerQuery": 20,
    "maxItems": 20,
    "deduplicateCodes": True,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/icd10-code-search-export").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 '{
  "queries": [
    "depression",
    "diabetes"
  ],
  "maxResultsPerQuery": 20,
  "maxItems": 20,
  "deduplicateCodes": true
}' |
apify call automation-lab/icd10-code-search-export --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/icd10-code-search-export"
        }
    }
}

```

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/BpiCrRBfKWytRnGlO/builds/X58CRD2ELLpTWb3ry/openapi.json