# Healthgrades Doctors & Profiles Scraper (`automation-lab/healthgrades-doctors-profiles-scraper`) Actor

Find public Healthgrades doctors and export detailed physician profiles with ratings, NPI, specialties, practices, contacts, education, affiliations, and review summaries.

- **URL**: https://apify.com/automation-lab/healthgrades-doctors-profiles-scraper.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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/platform/actors/running/actors-in-store#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.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md).

If your project is in a different language, use 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

## Healthgrades Doctors & Profiles Scraper

Turn public Healthgrades doctor directories and physician profiles into structured provider data.

Search by medical specialty and US location, crawl a public directory, and optionally enrich every result from its physician profile. Export names, NPI numbers, ratings, practice contacts, education, conditions, procedures, affiliations, awards, and public review summaries in one consistent dataset.

Use the data for healthcare lead research, provider-directory maintenance, clinic-network enrichment, referral research, and recurring reputation monitoring.

### What does Healthgrades Doctors & Profiles Scraper do?

The Actor supports three practical routes:

- 🔎 build a specialty/location directory URL from input fields;
- 🔗 scrape one or more public Healthgrades directory URLs;
- 👤 extract specific public physician profile URLs.

For directory inputs, it follows bounded pagination and deduplicates physicians by canonical profile URL.

When profile enrichment is enabled, each row gains the public details available on that provider page.

The result is a single provider entity per dataset row, ready for spreadsheets, databases, APIs, or scheduled monitoring.

### Who is it for?

#### Healthcare data and lead vendors

Build or refresh physician prospect lists with specialty, practice, location, phone, and NPI fields.

#### Clinic and health-network operations teams

Monitor public provider profiles, directory coverage, new-patient signals, affiliations, and contact details.

#### Referral and market researchers

Compare specialists by location, experience, patient rating, procedures, and hospital relationships.

#### Reputation teams

Schedule recurring runs and compare rating counts or public review summaries over time.

#### Developers and data engineers

Feed typed JSON records into enrichment pipelines, CRMs, warehouses, and internal provider search products.

### Why use this Actor?

- ✅ No Healthgrades login is required for the supported public scope.
- ✅ Directory and direct-profile inputs use the same output contract.
- ✅ Canonical Healthgrades URLs are preserved in every row.
- ✅ Pagination, deduplication, retries, and bounded concurrency are built in.
- ✅ Extraction fails closed when a page is blocked or does not contain provider data.
- ✅ Profile fields use semantic markup and Schema.org structured data where available.
- ✅ Optional directory-only mode reduces requests when basic discovery is enough.

### What Healthgrades data can I extract?

| Field | Description |
|---|---|
| `name` | Public doctor or physician name |
| `profileUrl` | Canonical Healthgrades physician URL |
| `providerId` | Healthgrades provider identifier |
| `npi` | Public National Provider Identifier when shown |
| `specialty` | Primary medical specialty |
| `secondarySpecialty` | Additional structured specialty or service |
| `rating` | Aggregate patient rating |
| `ratingCount` | Number of public ratings |
| `biography` | Public profile description |
| `acceptingNewPatients` | Public new-patient signal |
| `yearsExperience` | Experience years shown on the profile |
| `practiceName` | Public practice or office name |
| `phone` | Public office phone |
| `addresses` | Structured office addresses and coordinates |
| `education` | Public medical education entries |
| `boardCertifications` | Public certification names |
| `conditionsTreated` | Conditions listed in profile metadata |
| `proceduresPerformed` | Procedures listed in profile metadata |
| `experienceHighlights` | Public experience comparison statements |
| `hospitalAffiliations` | Public hospital names and addresses |
| `awards` | Public profile or hospital awards |
| `reviews` | Public review summary text, rating, and date |
| `insuranceCheckAvailable` | Whether the profile exposes its insurance checker |
| `profileComplete` | Whether the detailed profile was fetched |
| `sourceDirectoryUrl` | Directory that discovered the physician |
| `scrapedAt` | ISO extraction timestamp |

Fields not present on a particular public profile are omitted rather than filled with invented values.

### How to scrape Healthgrades doctors by specialty and city

1. Open the Actor input page.
2. Remove the sample URL from **Healthgrades URLs**.
3. Enter a specialty such as `Cardiology`.
4. Enter `New York`, `NY`, and `New York` in the location fields.
5. Choose a small `maxItems` value for the first run.
6. Keep **Open provider profiles** enabled for detailed enrichment.
7. Start the run and export the resulting dataset.

Example:

```json
{
  "specialty": "Cardiology",
  "city": "New York",
  "stateCode": "NY",
  "stateName": "New York",
  "maxItems": 20,
  "maxPages": 2,
  "includeProfileDetails": true,
  "maxConcurrency": 3
}
````

### How to extract specific Healthgrades physician profiles

Paste one or more public `/physician/` URLs into `startUrls`.

```json
{
  "startUrls": [
    { "url": "https://www.healthgrades.com/physician/dr-jennifer-liu-24lgh" }
  ],
  "maxItems": 1,
  "includeProfileDetails": true,
  "maxConcurrency": 1
}
```

This mode is useful when another system already knows the canonical Healthgrades profile URL.

### Input reference

#### `startUrls`

An array of public Healthgrades specialty directory or physician profile URLs.

Supported paths include:

- `https://www.healthgrades.com/cardiology-directory/ny-new-york/new-york`
- `https://www.healthgrades.com/physician/dr-jennifer-liu-24lgh`

Unrelated hosts and unsupported Healthgrades paths are rejected.

#### Specialty and location fields

`specialty`, `city`, `stateCode`, and `stateName` must all be supplied when no URL is provided.

#### `maxItems`

Maximum unique provider records across all inputs. Default: `20`.

#### `includeProfileDetails`

Set to `false` for fast directory-card records. Default: `true`.

#### `maxPages`

Maximum pages followed per directory. Default: `5`.

#### `maxConcurrency`

Parallel profile requests, from 1 to 8. Default: `3`.

### Output example

```json
{
  "name": "Dr. Jennifer Liu, MD",
  "profileUrl": "https://www.healthgrades.com/physician/dr-jennifer-liu-24lgh",
  "providerId": "24LGH",
  "npi": "1447321534",
  "specialty": "Cardiology",
  "rating": 5,
  "ratingCount": 1,
  "acceptingNewPatients": true,
  "practiceName": "Memorial Sloan Kettering Cancer Center",
  "phone": "(929)379-4880",
  "conditionsTreated": ["Hypertension", "Atrial Fibrillation"],
  "profileComplete": true,
  "scrapedAt": "2026-07-24T07:20:23.522Z"
}
```

The complete record can also contain nested addresses, education, affiliations, awards, and review summaries.

### Directory-only versus detailed profile mode

Choose directory-only mode when you need:

- provider discovery;
- names and canonical profile URLs;
- basic specialty, rating, biography, image, and address data;
- fewer requests and faster recurring checks.

Choose detailed profile mode when you need:

- NPI and structured rating data;
- public practice and phone details;
- education and certification information;
- conditions, procedures, experience, and affiliations;
- awards and public review summaries.

### How much does it cost to scrape Healthgrades doctor profiles?

The Actor uses pay-per-event pricing.

- Run start: **$0.0005**
- Doctor profile at BRONZE tier: **$0.00026323 per saved provider**

Higher Apify subscription tiers receive automatic volume discounts on the per-provider event. You can set `maxItems` and an Apify maximum run charge to control spend.

Start with 5 providers to validate the result shape before scheduling a larger directory run.

### Export formats

Apify datasets support:

- JSON
- CSV
- Excel
- XML
- RSS
- JSONL

Nested fields are most naturally preserved in JSON or JSONL. CSV and Excel are convenient for provider contact and rating lists.

### Scheduling provider monitoring

Use an Apify schedule to run the same directory daily, weekly, or monthly.

A downstream workflow can compare:

- rating and rating-count changes;
- practice or phone changes;
- new-patient status;
- new or removed directory profiles;
- hospital affiliation changes;
- profile completeness and extraction timestamps.

Store snapshots in your own database if historical comparisons are required.

### Integrations

#### Google Sheets

Send each completed dataset to a sheet for research and outreach review.

#### CRM enrichment

Match `npi`, `name`, `practiceName`, `phone`, and addresses to existing provider records.

#### Webhooks

Trigger a webhook when a scheduled run finishes, then fetch the dataset through the API.

#### Make and Zapier

Use Apify integrations to route new provider rows into alerts, spreadsheets, or enrichment workflows.

#### Data warehouses

Load JSONL into BigQuery, Snowflake, PostgreSQL, or another analytical store.

### Use the Actor with the Apify API

Replace `TOKEN` with your Apify API token.

#### cURL

```bash
curl -X POST "https://api.apify.com/v2/acts/automation-lab~healthgrades-doctors-profiles-scraper/runs?token=TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"startUrls":[{"url":"https://www.healthgrades.com/physician/dr-jennifer-liu-24lgh"}],"maxItems":1}'
```

#### JavaScript

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/healthgrades-doctors-profiles-scraper').call({
  specialty: 'Cardiology',
  city: 'New York',
  stateCode: 'NY',
  stateName: 'New York',
  maxItems: 20,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient("TOKEN")
run = client.actor("automation-lab/healthgrades-doctors-profiles-scraper").call(run_input={
    "startUrls": [{"url": "https://www.healthgrades.com/physician/dr-jennifer-liu-24lgh"}],
    "maxItems": 1,
})
items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items)
```

### Use Healthgrades data with MCP

Connect Apify Actors to supported AI clients through the Apify MCP server.

Use this MCP URL:

`https://mcp.apify.com/?tools=automation-lab/healthgrades-doctors-profiles-scraper`

Example prompts:

- “Extract 20 cardiologists in New York from Healthgrades and summarize their ratings.”
- “Enrich these Healthgrades physician URLs with NPI, practice, phone, and affiliations.”
- “Compare this week's provider rating counts with last week's dataset.”

#### Claude Code setup

```bash
claude mcp add --transport http apify-healthgrades "https://mcp.apify.com/?tools=automation-lab/healthgrades-doctors-profiles-scraper"
```

#### Claude Desktop setup

Add this remote server to the Claude Desktop MCP configuration.

#### Cursor setup

Add the same server object to Cursor's MCP settings.

#### VS Code setup

Add the server to your VS Code MCP configuration and authenticate through Apify when prompted.

Claude Desktop, Cursor, and VS Code JSON:

```json
{
  "mcpServers": {
    "apify-healthgrades": {
      "url": "https://mcp.apify.com/?tools=automation-lab/healthgrades-doctors-profiles-scraper"
    }
  }
}
```

### Data quality and freshness

The Actor extracts what is publicly rendered at run time.

Healthgrades profiles vary in completeness. A provider may not publish every supported field.

`profileComplete: true` means the profile page was fetched and parsed; it does not mean every optional field exists.

Canonical profile URLs and `scrapedAt` make records easier to deduplicate and compare.

### Reliability and anti-bot handling

Healthgrades can restrict direct page delivery by geography.

The Actor uses a validated public rendering route, conservative concurrency, bounded retries, and semantic selectors.

Do not increase concurrency aggressively. Lower it if a large scheduled run encounters transient delivery errors.

A blocked or malformed response fails the run instead of silently saving empty provider shells.

### Limitations

- Only public Healthgrades specialty directory and physician profile pages are supported.
- General search pages, facilities, pharmacies, and authenticated workflows are outside scope.
- The interactive insurance checker is detected, but a complete plan list is not claimed when plans are not rendered publicly.
- Review output is limited to public review summaries embedded in the profile page.
- Fields can change when Healthgrades updates its public markup.
- US directory URL construction requires specialty, city, state code, and full state name.

### Legal and responsible use

Public availability does not remove your compliance obligations.

Use the Actor only for lawful purposes and data you are authorized to process. Review applicable website terms, privacy rules, healthcare marketing requirements, and regional data-protection laws.

Avoid using scraped data for sensitive decisions about individuals. Do not infer medical conditions, protected characteristics, or professional quality beyond what the source explicitly publishes.

Respect opt-outs and retention requirements in your downstream systems.

### Troubleshooting

#### Why did my run reject a URL?

The Actor accepts only public Healthgrades specialty directory and `/physician/` paths. Check the hostname and path.

#### Why are some fields missing?

Provider profiles vary. Optional fields are omitted when Healthgrades does not publish them.

#### Why did the run fail with no providers?

Confirm that the directory exists, the location slug is correct, and the page currently contains public physician cards.

#### How can I reduce requests?

Set `includeProfileDetails` to `false` to save directory-card records without opening each profile.

#### How should I handle transient delivery errors?

Retry later or reduce `maxConcurrency`. Keep pagination and item limits bounded.

### FAQ

#### Does this Actor require a Healthgrades account?

No. The supported scope uses public directory and physician profile pages.

#### Can I scrape several directories in one run?

Yes. Add multiple directory URLs to `startUrls`; physicians are deduplicated by canonical profile URL.

#### Can I scrape one known doctor?

Yes. Supply the public Healthgrades physician profile URL directly.

#### Are insurance plans included?

The output reports whether the public insurance checker is available. It does not invent or imply a complete plan list when Healthgrades does not render one.

#### Can I schedule recurring checks?

Yes. Use Apify schedules and retain previous datasets in your own system for comparisons.

#### Does the Actor return reviews?

It returns public review summaries embedded in structured profile data when available, not an unlimited review-history crawler.

### Related healthcare Actors

Combine this Actor with other Automation Lab public-data tools when the workflow requires broader healthcare context:

- [NPI Registry Provider Scraper](https://apify.com/automation-lab/npi-registry-provider-scraper)
- [Hospital Compare Medicare Scraper](https://apify.com/automation-lab/hospital-compare-medicare-scraper)
- [Hospital Price Transparency Scraper](https://apify.com/automation-lab/hospital-price-transparency-scraper)
- [HHS OIG Exclusions List Scraper](https://apify.com/automation-lab/hhs-oig-exclusions-list-scraper)

Use only related Actors whose source and contract fit your compliance requirements.

### Start scraping Healthgrades doctors

Run the prefilled example for five New York cardiologists, inspect the dataset, then scale `maxItems` for your provider research or monitoring workflow.

# Actor input Schema

## `startUrls` (type: `array`):

Public Healthgrades specialty directory or physician profile URLs. Leave empty to build a directory URL from the location fields below.

## `specialty` (type: `string`):

Specialty used to construct a directory URL, for example Cardiology or Family Medicine.

## `city` (type: `string`):

US city name, for example New York.

## `stateCode` (type: `string`):

Two-letter US state code, for example NY.

## `stateName` (type: `string`):

Full US state name, for example New York.

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

Maximum unique provider records saved across all supplied directories and profiles.

## `includeProfileDetails` (type: `boolean`):

Follow each directory result to collect NPI, practice, phone, education, conditions, procedures, affiliations, awards, and review summaries.

## `maxPages` (type: `integer`):

Safety limit for pagination per directory URL.

## `maxConcurrency` (type: `integer`):

Number of provider profiles fetched in parallel. Keep this low for reliable Healthgrades extraction.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://www.healthgrades.com/cardiology-directory/ny-new-york/new-york"
    }
  ],
  "maxItems": 5,
  "includeProfileDetails": true,
  "maxPages": 1,
  "maxConcurrency": 2
}
```

# Actor output Schema

## `overview` (type: `string`):

Open the extracted provider records in the Doctors dataset view.

# 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 = {
    "startUrls": [
        {
            "url": "https://www.healthgrades.com/cardiology-directory/ny-new-york/new-york"
        }
    ],
    "maxItems": 5,
    "includeProfileDetails": true,
    "maxPages": 1,
    "maxConcurrency": 2
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/healthgrades-doctors-profiles-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 = {
    "startUrls": [{ "url": "https://www.healthgrades.com/cardiology-directory/ny-new-york/new-york" }],
    "maxItems": 5,
    "includeProfileDetails": True,
    "maxPages": 1,
    "maxConcurrency": 2,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/healthgrades-doctors-profiles-scraper").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "startUrls": [
    {
      "url": "https://www.healthgrades.com/cardiology-directory/ny-new-york/new-york"
    }
  ],
  "maxItems": 5,
  "includeProfileDetails": true,
  "maxPages": 1,
  "maxConcurrency": 2
}' |
apify call automation-lab/healthgrades-doctors-profiles-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=automation-lab/healthgrades-doctors-profiles-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Healthgrades Doctors & Profiles Scraper",
        "description": "Find public Healthgrades doctors and export detailed physician profiles with ratings, NPI, specialties, practices, contacts, education, affiliations, and review summaries.",
        "version": "0.1",
        "x-build-id": "I6guSu4qy8gdXzS2i"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/automation-lab~healthgrades-doctors-profiles-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-automation-lab-healthgrades-doctors-profiles-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/automation-lab~healthgrades-doctors-profiles-scraper/runs": {
            "post": {
                "operationId": "runs-sync-automation-lab-healthgrades-doctors-profiles-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/automation-lab~healthgrades-doctors-profiles-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-automation-lab-healthgrades-doctors-profiles-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "properties": {
                    "startUrls": {
                        "title": "🔗 Healthgrades URLs",
                        "type": "array",
                        "description": "Public Healthgrades specialty directory or physician profile URLs. Leave empty to build a directory URL from the location fields below.",
                        "items": {
                            "type": "object",
                            "required": [
                                "url"
                            ],
                            "properties": {
                                "url": {
                                    "type": "string",
                                    "title": "URL of a web page",
                                    "format": "uri"
                                }
                            }
                        }
                    },
                    "specialty": {
                        "title": "Medical specialty",
                        "type": "string",
                        "description": "Specialty used to construct a directory URL, for example Cardiology or Family Medicine."
                    },
                    "city": {
                        "title": "City",
                        "type": "string",
                        "description": "US city name, for example New York."
                    },
                    "stateCode": {
                        "title": "State code",
                        "minLength": 2,
                        "maxLength": 2,
                        "type": "string",
                        "description": "Two-letter US state code, for example NY."
                    },
                    "stateName": {
                        "title": "State name",
                        "type": "string",
                        "description": "Full US state name, for example New York."
                    },
                    "maxItems": {
                        "title": "Maximum doctors",
                        "minimum": 1,
                        "maximum": 10000,
                        "type": "integer",
                        "description": "Maximum unique provider records saved across all supplied directories and profiles.",
                        "default": 20
                    },
                    "includeProfileDetails": {
                        "title": "Open provider profiles",
                        "type": "boolean",
                        "description": "Follow each directory result to collect NPI, practice, phone, education, conditions, procedures, affiliations, awards, and review summaries.",
                        "default": true
                    },
                    "maxPages": {
                        "title": "Maximum directory pages",
                        "minimum": 1,
                        "maximum": 100,
                        "type": "integer",
                        "description": "Safety limit for pagination per directory URL.",
                        "default": 5
                    },
                    "maxConcurrency": {
                        "title": "Profile request concurrency",
                        "minimum": 1,
                        "maximum": 8,
                        "type": "integer",
                        "description": "Number of provider profiles fetched in parallel. Keep this low for reliable Healthgrades extraction.",
                        "default": 3
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
