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 in default search mode. Select exactCode for whole-code equality, including compact inputs such as f32a or E119, or codePrefix to restrict matches to a normalized code family such as E11. Each run uses one mode for all queries; default search remains NLM code/title matching, not exact equality.

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.
queryMode	string	search	search, exactCode, or codePrefix, applied to every query.
maxResultsPerQuery	integer	20	Per-query source-match ceiling before deduplication, from 1 to 5,000, also bounded by remaining maxItems.
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, non-string entries, strings longer than 2,000 characters, and more than 20 queries fail clearly. Code modes accept three-character categories plus up to four alphanumeric characters, with an optional dot after the category; they trim whitespace, uppercase, and insert the dot in compact codes. Malformed code intent never falls back to free-text search. Identical trimmed queries execute only once in search mode (existing behavior), but every input has its own summary outcome; code modes execute every input for code-duplicate accounting.

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.

Exact compact-code normalization

{
  "queries": ["f32a", "E119", "F32.A"],
  "queryMode": "exactCode",
  "maxResultsPerQuery": 20,
  "maxItems": 20,
  "deduplicateCodes": true
}

This returns only F32.A and E11.9, with the first input context retained for duplicate codes. E11.2 is not returned as an exact code if NLM only exposes descendants such as E11.21.

Export the E11 code family

{
  "queries": ["E11"],
  "queryMode": "codePrefix",
  "maxResultsPerQuery": 100,
  "maxItems": 100,
  "deduplicateCodes": true
}

Use prefix lookups to build a bounded source-backed code family export. To cross the first pagination boundary, use {"queries":["S52"],"queryMode":"codePrefix","maxResultsPerQuery":600,"maxItems":600}. This requests two pages (500 then up to 100), not a full corpus download.

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 (original code-mode input; trimmed in search mode).
normalizedQuery	Term used for matching; upper-case dotted code intent in code modes.
queryMode	search, exactCode, or codePrefix.
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	Source-reported total before local verification; may be capped at 10,000 and is not a completeness guarantee.
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",
  "normalizedQuery": "depression",
  "queryMode": "search",
  "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&count=25&offset=0",
  "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, rejected duplicate rows, or the query summary. These event charges are the Actor price; owner platform compute usage is distinct. The Actor stops before writing records beyond the remaining event budget. A dataset-write or charge failure fails the run visibly and is not retried automatically; partial output from a failed run is not a successful export.

Query completeness summary

The Output tab also links to the non-billable SEARCH_SUMMARY JSON record in the run's key-value store, including when the dataset is empty. schemaVersion: 1 records totalSavedCount, a run-level stopReason, and per-input queryIndex, duplicateOfQueryIndex, queryMode, normalizedCode (code modes only), sourceReportedTotal, sourceTotalMayBeCapped, examinedCount, returnedCount (after exact/prefix verification, before dedup), savedCount, duplicatesRemoved, pages, offsets, outcome, and stopReason.

Outcomes distinguish zeroMatches, complete, truncated, notAttempted, failed, and duplicateInput. Reasons identify source exhaustion, per-query/total caps, charge limits, time budget, cancellation, or fatal errors. Later queries blocked by the total cap are unattempted, not zero-match. The per-query request ceiling is min(maxResultsPerQuery, remaining maxItems); deduplication does not refill that ceiling. Ranks preserve source positions across pages and may have gaps after filtering/deduplication.

To protect private search text, the summary omits raw queries. Every supplied input has one outcome, and queryIndex is its zero-based index in the original input array. An identical trimmed search input has outcome and stopReason equal to duplicateInput, with duplicateOfQueryIndex pointing to its first occurrence; all execution counts are zero and its source total is null because it makes no request. Consult the referenced occurrence for its completion, cap, or failure outcome, even if execution stops before reaching the duplicate. Independently executed inputs have duplicateOfQueryIndex: null. For example, ["depression", " depression ", "E11"] produces indices 0, 1, 2; index 1 references 0, and E11 remains index 2. This input collapse is distinct from duplicatesRemoved, which counts returned code rows removed by code deduplication. Compact/dotted code queries execute separately. Partial safe progress is persisted before failing on a source error; completeness is never asserted across a missing, repeated, malformed, or short non-final page. Normal budget/time stops produce an explicit bounded result, not a full-export claim.

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 pagination uses count (at most 500 per page) and zero-based offset; its documented retrieval ceiling is 7,500. This Actor requests at most 5,000 per query and saves at most 5,000 per run.
• The reported total may exceed returned rows and may be capped at 10,000; inspect the summary rather than treating it as an exact corpus count.
• 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 429/5xx and network/timeouts receive at most three bounded attempts with backoff. Permanent 4xx and malformed-success payloads fail immediately, without retrying.
• 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 uses no AI models or external model providers. It is independently operated and is not affiliated with or endorsed by NLM, CMS, or Apify.

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 safe upstream status/phase evidence without exposing private query text in logs or diagnostics.

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.

Sanitized failure diagnostics

Failed operations send sanitized diagnostic input, exceptions, and Actor/build/run IDs to our private GlitchTip service for repair. Secret fields and URL queries are removed; this Actor additionally redacts all raw lookup queries from SDK reports and terminal webhooks. Reports are retained for 30 days. Search terms remain in your own input and dataset provenance, not in the query summary. Run datasets, input, summary, and logs are stored in your Apify account under Apify's account retention settings; delete the run storage through Console/API when no longer needed. The Actor creates no cross-run cache or private copy of these records. Lookup text is sent to the public NLM service to perform the requested search, without authentication or patient identifiers; do not assume that an upstream service offers private processing. Never submit patient data.

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.