{ "openapi": "3.0.1", "info": { "title": "Medicare Advantage Competitive Intelligence Monitor", "description": "Track Medicare Advantage plans, enrollment, county market share, Star Ratings and competitor changes from public CMS data. Detect plan launches, exits, growth, rating changes and geographic expansion.", "version": "0.1", "x-build-id": "enVtGUl3Wy9vWi2Gd" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/huykenny~medicare-advantage-competitive-intelligence/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-huykenny-medicare-advantage-competitive-intelligence", "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/huykenny~medicare-advantage-competitive-intelligence/runs": { "post": { "operationId": "runs-sync-huykenny-medicare-advantage-competitive-intelligence", "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/huykenny~medicare-advantage-competitive-intelligence/run-sync": { "post": { "operationId": "run-sync-huykenny-medicare-advantage-competitive-intelligence", "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": { "outputMode": { "title": "Output mode", "enum": [ "signals", "plans", "county-market", "carriers" ], "type": "string", "description": "\"Competitive signals\": only detected changes, ranked by significance. \"Plans\": one row per Medicare Advantage plan with enrollment, ratings and trend. \"County market\": one row per plan per county with market share and rank. \"Carriers\": one row per parent organization.", "default": "signals" }, "signalScope": { "title": "Signal detail level", "enum": [ "plan", "county", "both" ], "type": "string", "description": "Only applies when the output mode is \"Competitive signals\". Plan level covers plan launches and exits, plan enrollment moves, carrier moves and county service-area changes. County level adds per-county enrollment and market-share movement, which is far more granular and much larger nationwide. Narrowing by state or county turns county-level signals on automatically.", "default": "plan" }, "signalTypes": { "title": "Only these signal types", "type": "array", "description": "Leave empty for every signal type. Use this to build a focused feed, for example only plan launches and exits, or only Star Rating movement.", "items": { "type": "string", "enum": [ "NEW_PLAN", "PLAN_EXIT", "NEW_COUNTY", "COUNTY_EXIT", "COUNTY_ENROLLMENT_START", "COUNTY_ENROLLMENT_STOP", "ENROLLMENT_GROWTH", "ENROLLMENT_DECLINE", "STAR_RATING_UP", "STAR_RATING_DOWN", "MARKET_SHARE_GAIN", "MARKET_SHARE_LOSS" ], "enumTitles": [ "NEW_PLAN — a plan appeared in CMS data", "PLAN_EXIT — a plan disappeared from CMS data", "NEW_COUNTY — a carrier added a county to a contract's approved service area", "COUNTY_EXIT — a carrier dropped a county from a contract's approved service area", "COUNTY_ENROLLMENT_START — a plan rose above CMS's county reporting threshold", "COUNTY_ENROLLMENT_STOP — a plan fell below CMS's county reporting threshold", "ENROLLMENT_GROWTH — enrollment rose past your thresholds", "ENROLLMENT_DECLINE — enrollment fell past your thresholds", "STAR_RATING_UP — a contract's overall Star Rating rose", "STAR_RATING_DOWN — a contract's overall Star Rating fell", "MARKET_SHARE_GAIN — county market share rose", "MARKET_SHARE_LOSS — county market share fell" ] } }, "currentPeriod": { "title": "Current period", "type": "string", "description": "CMS month to analyse, as YYYY-MM, for example \"2026-08\". Leave empty for the newest published month." }, "previousPeriod": { "title": "Compare against", "type": "string", "description": "CMS month to compare against, as YYYY-MM. Leave empty to use the newest published month older than the current period. Note that CMS never published 2019-11 or 2023-07." }, "organizations": { "title": "Organizations", "type": "array", "description": "Match against parent organization, legal organization name or marketing name. Case-insensitive and matches on part of a name, so \"humana\" matches \"Humana Inc.\". Leave empty for all carriers.", "items": { "type": "string" } }, "contractIds": { "title": "Contract IDs", "type": "array", "description": "CMS contract IDs, for example \"H0028\". Leave empty for all contracts.", "items": { "type": "string" } }, "planIds": { "title": "Plan IDs", "type": "array", "description": "CMS plan IDs within a contract, three digits, for example \"009\". Only useful together with a contract ID.", "items": { "type": "string" } }, "states": { "title": "US states", "type": "array", "description": "Two-letter state codes, for example \"TX\". Leave empty for all states.", "items": { "type": "string" } }, "counties": { "title": "Counties", "type": "array", "description": "County FIPS codes (preferred, for example \"48201\" for Harris County, Texas) or county names as CMS publishes them, without the word \"County\". FIPS is more reliable, because county names differ between CMS files.", "items": { "type": "string" } }, "planTypes": { "title": "Plan types", "type": "array", "description": "Leave empty for all plan types. The original CMS plan-type text is always kept in the output's rawPlanType field.", "items": { "type": "string", "enum": [ "HMO", "PPO", "PFFS", "MSA", "Cost", "PACE", "PDP", "other" ], "enumTitles": [ "HMO / HMO-POS", "PPO (local and regional)", "PFFS — Private Fee-For-Service", "MSA — Medical Savings Account", "Cost plan (only with the wider plan universe)", "PACE (only with the wider plan universe)", "PDP — standalone Part D (only with the wider plan universe)", "Other" ] } }, "snpOnly": { "title": "Special Needs Plans only", "type": "boolean", "description": "Return only Special Needs Plans (SNPs).", "default": false }, "snpTypes": { "title": "SNP types", "type": "array", "description": "Filter to specific SNP subtypes. Subtypes come from the CMS SNP Comprehensive Report, so this needs the SNP detail source switched on below.", "items": { "type": "string", "enum": [ "C-SNP", "D-SNP", "I-SNP" ], "enumTitles": [ "C-SNP — chronic or disabling condition", "D-SNP — dual-eligible", "I-SNP — institutional" ] } }, "planUniverse": { "title": "Plan universe", "enum": [ "medicare-advantage", "all" ], "type": "string", "description": "CMS ships standalone Part D, PACE and Cost plans in the same files as Medicare Advantage. They are different markets, and including them would put non-MA volume into every enrollment total and market share, so they are excluded by default.", "default": "medicare-advantage" }, "minStarRating": { "title": "Minimum Star Rating", "minimum": 1, "maximum": 5, "type": "number", "description": "Only include contracts whose overall Star Rating is at least this value. Ratings move in half stars, so 3.5 and 4.5 are valid." }, "maxStarRating": { "title": "Maximum Star Rating", "minimum": 1, "maximum": 5, "type": "number", "description": "Only include contracts whose overall Star Rating is at most this value. Useful for finding underperforming competitors. Half stars are valid." }, "minEnrollment": { "title": "Minimum enrollment", "minimum": 0, "type": "integer", "description": "Only include plans at or above this enrollment. Suppressed values are kept, since their true size is unknown." }, "maxEnrollment": { "title": "Maximum enrollment", "minimum": 0, "type": "integer", "description": "Only include plans at or below this enrollment." }, "minEnrollmentChangePercent": { "title": "Minimum enrollment change", "minimum": 0, "type": "number", "description": "An enrollment signal needs both this percentage change and the absolute change below it. Requiring both is what stops a plan moving from 11 to 13 members being reported as 18% growth.", "default": 10 }, "minEnrollmentChangeAbsolute": { "title": "Minimum enrollment change (members)", "minimum": 0, "type": "integer", "description": "The second half of the noise floor. Raise it to see only large movements; lower it to catch small plans.", "default": 25 }, "minMarketSharePercent": { "title": "Minimum county market share", "minimum": 0, "maximum": 100, "type": "number", "description": "Only include county rows where the plan holds at least this share of the county's Medicare Advantage enrollment." }, "minMarketShareChangePp": { "title": "Minimum market-share move", "minimum": 0, "type": "number", "description": "A market-share signal needs a move of at least this many percentage points. A plan going from 8% to 10% of a county moved 2 percentage points.", "default": 0.5 }, "deltaMode": { "title": "What to return each run", "enum": [ "all", "changes-only", "new-only" ], "type": "string", "description": "\"Everything\": the full current result each run. \"Changes only\": skip rows you have already been given unchanged. \"New only\": the cleanest feed for scheduled alerts.", "default": "all" }, "stateStoreName": { "title": "Monitoring name", "type": "string", "description": "Identifies this monitor so the Actor remembers what it last showed you. Use the same value on every scheduled run for one purpose, and a different value to start an independent monitor.", "default": "medicare-advantage-monitor-state" }, "skipWhenNoNewCmsPeriod": { "title": "Skip when CMS has published nothing new", "type": "boolean", "description": "On by default. When this monitor has already answered the same request for the newest CMS month, the run finishes immediately without downloading anything, so a daily schedule costs only the Actor start fee. Changing any filter counts as a different request and always runs in full. Turn this off to force a complete run every time.", "default": true }, "initializeStateOnly": { "title": "Baseline-only first run (no output)", "type": "boolean", "description": "Turn this on for the very first run of a new monitoring name: it records the current picture as your baseline and returns no rows, so your next run shows only genuine movement.", "default": false }, "emitRemovedRecords": { "title": "Include records that disappeared", "type": "boolean", "description": "Include rows for plans or county positions that vanished since your last run. Only ever applies when the Actor could confirm a complete, unfiltered download — see the README's removal-safety section.", "default": true }, "includeStarRatings": { "title": "Include Star Ratings", "type": "boolean", "description": "Fetch the current and previous Part C and Part D Star Ratings years. Turning this off removes all rating fields and rating signals and makes the run slightly faster.", "default": true }, "includeSnpDetail": { "title": "Include SNP detail", "type": "boolean", "description": "Fetch the CMS SNP Comprehensive Report for SNP subtype, specialty diseases, integration status and plan segment IDs. This is the only CMS file that publishes segment IDs.", "default": true }, "includeEmployerGroupPlans": { "title": "Include employer-group service areas", "type": "boolean", "description": "The CMS service-area file is 89% employer-group-only rows, which describe coverage sold through employers rather than the individual Medicare market. They are excluded by default.", "default": false }, "includeSuppressedRows": { "title": "Include suppressed county rows", "type": "boolean", "description": "CMS suppresses county cells with 10 or fewer members. Including them adds about 3.2 million rows nationwide, so this is honoured only when the run is narrowed to specific states or counties. Enrollment stays null on these rows; it is never guessed.", "default": false }, "maxItems": { "title": "Maximum rows", "minimum": 1, "type": "integer", "description": "Stop after this many rows. Useful for a cheap trial run. Note that limiting rows makes the run incomplete, which switches off every signal that claims something disappeared." }, "debug": { "title": "Debug logging", "type": "boolean", "description": "Log every source URL, row count and filter decision. Useful when a run returns less than you expected.", "default": false } } }, "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 } } } } } } } } } }