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 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:

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

ICD-10 codes lookup examples

Find ICD-10 codes for depression

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

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

Export the E11 code family

{
  "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

{
  "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

{
  "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

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

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

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:

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:

{
  "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 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.