# US Visa Bulletin Priority Date Monitor (`nerolabs/us-visa-bulletin-monitor`) Actor

Returns US green card priority date cutoffs per category and country from the State Department Visa Bulletin, whether your date is current, and monthly movement. Inputs: category, country, priority date, monitorMode. Agent-ready: pay per event (x402 and MCP); not-published is charged.

- **URL**: https://apify.com/nerolabs/us-visa-bulletin-monitor.md
- **Developed by:** [Adam Pearce](https://apify.com/nerolabs) (community)
- **Categories:** Business, Automation, Agents
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 visa bulletin lookups

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## US Visa Bulletin Priority Date Monitor

**Is your green card priority date current yet? Did the cutoff move this month?** This Actor reads the U.S. Department of State's monthly [Visa Bulletin](https://travel.state.gov/content/travel/en/legal/visa-law0/visa-bulletin.html) and tells you the exact priority-date cutoff for any category and country, whether a given priority date is current, and, in monitor mode, exactly how many days a cutoff advanced or retrogressed since last month.

Built for **immigration attorneys, paralegals, and green card applicants** who check the Visa Bulletin every single month while waiting, sometimes for years, for a priority date to become current. It runs on the Apify platform, so you get API access, monthly scheduling, integrations, and email/Slack alerts on top of the raw data.

### Why use the US Visa Bulletin Priority Date Monitor?

- **Stop reading the tables by hand.** Enter a category (F2A, EB-2, EB-3...) and a country (India, China, Mexico, Philippines, or worldwide) and get the cutoff back as clean, structured data.
- **Answer the real question: "is my date current?"** Give it a priority date and it applies the Bulletin's own rule (numbers issue only to dates *earlier* than the cutoff) and tells you yes or no, in plain English.
- **Catch movement automatically.** Monitor mode compares this month against last month and reports only what actually moved: advanced N days, retrogressed N days, became Current, or became Unavailable. Schedule it once and get alerted when a watched category finally moves.
- **Track a whole caseload in one run.** Pass a list of client targets and check dozens of category/country combinations in a single, cheap run.
- **Read any past month too.** Pull the cutoffs from any historical bulletin back to 2001, not just the current one.

### How to use it

1. Click **Try for free**.
2. (Optional) Turn on **Reference mode** first to see every valid category code, country, and available month.
3. Enter a **category** (e.g. `EB-2`) and a **country** (e.g. `India`). Optionally add a **priority date** (`YYYY-MM-DD`) to get a current/not-current verdict.
4. To watch for movement over time, turn on **Monitor mode** and set a monthly schedule. The first run records a baseline; later runs report only real changes.
5. Run it and read the results in the **Output** tab, or pull them from the API.

### Input

- **Category** - Family (`F1`, `F2A`, `F2B`, `F3`, `F4`) or Employment (`EB-1` to `EB-5`, plus `Other Workers`, `Certain Religious Workers`, and the EB-5 set-asides).
- **Country of chargeability** - `worldwide`, `China`, `India`, `Mexico`, or `Philippines` (the only five columns the Bulletin publishes).
- **Which chart** - Final Action Dates (when a green card can be issued) or Dates for Filing (when documents can be submitted).
- **Priority date** (optional) - `YYYY-MM-DD`. Returns a current / not-current verdict.
- **Which month** - `latest` (default) or a specific month like `August 2026` / `2026-08`.
- **Targets** - An array to check many category/country combinations in one run.
- **Monitor mode** + **Watchlist ID** - Report only month-over-month movement, keeping separate histories per watchlist.

### Output

Each target returns one dataset row. Example:

```json
{
  "label": "Client A - EB2 India",
  "chart": "employment",
  "dateType": "final_action",
  "category": "2nd",
  "country": "India",
  "bulletinMonth": "August 2026",
  "found": true,
  "cutoff": "01SEP21",
  "cutoffStatus": "date",
  "cutoffDate": "2021-09-01",
  "priorityDate": "2019-01-01",
  "isCurrent": true,
  "verdict": "Priority date 2019-01-01 is earlier than the 01SEP21 cutoff, so it is current and can proceed.",
  "changeDetected": true,
  "movementKind": "advancement",
  "daysMoved": 92,
  "changeSummary": "Advanced 92 days (July 2026 to August 2026): from 01JUN21 to 01SEP21.",
  "sourceUrl": "https://travel.state.gov/content/travel/en/legal/visa-law0/visa-bulletin/2026/visa-bulletin-for-august-2026.html"
}
```

You can download the dataset in JSON, CSV, Excel, or HTML.

#### Data fields

| Field | Description |
|---|---|
| `category` / `country` | The category and country of chargeability checked |
| `chart` / `dateType` | family/employment, and final\_action or dates\_for\_filing |
| `bulletinMonth` | Which month's bulletin the figures came from |
| `cutoff` / `cutoffStatus` / `cutoffDate` | The raw cutoff (`01SEP21`, `C`, `U`), its status, and the ISO date |
| `isCurrent` / `verdict` | Whether the supplied priority date is current, in plain English |
| `movementKind` / `daysMoved` / `changeSummary` | Month-over-month movement in monitor mode |

### Pricing

This Actor uses **pay per event**. There is a small fixed fee per run (it opens one browser session to get past the source's bot protection), then **$0.01 per target looked up**. In monitor mode, a detected change is **$0.05** and a confirmed no-change is **$0.002**. Checking an entire caseload of, say, 20 category/country combinations in one monthly monitor run costs only a few cents. Because one run reads the whole bulletin, batching many targets into a single run is far cheaper than one run each.

### Tips

- Batch every client/target into a single run: the browser session is shared, so 30 targets cost almost the same as 1.
- Use a distinct **Watchlist ID** per client list so their baselines don't overwrite each other.
- Schedule monitor mode for the middle of the month; the State Department typically publishes the next month's bulletin around the 10th-15th.

### FAQ and support

**Is this legal?** Yes. The Visa Bulletin is a U.S. Government work in the public domain (17 U.S.C. Sec. 105), and the State Department's own copyright page states its Consular Affairs information "is in the public domain and may be copied and distributed without permission." This Actor reads only that published bulletin and uses no State Department seal or branding.

**Is this legal or immigration advice?** No. This Actor reports the published figures and applies the Bulletin's own current/not-current rule. It is not a substitute for advice from a licensed immigration attorney, and it does not access anyone's personal case.

**Which chart should I use?** Most people watching for their green card want **Final Action Dates**. **Dates for Filing** is when USCIS may let you submit documents earlier; check the USCIS "visa bulletin info" page for whether it applies in a given month.

**Found a bug or want another feature?** Open an issue on the Actor's Issues tab. If this saved you a manual check of the Visa Bulletin, a review really helps.

# Actor input Schema

## `listAvailableOptions` (type: `boolean`):

Turn this on to see the valid category codes (F1-F4, EB-1 to EB-5), country names, and every month the Visa Bulletin is published for. This mode is never charged. Use it first if you're not sure what to enter.

## `category` (type: `string`):

Green-card category. Family: F1, F2A, F2B, F3, F4. Employment: EB-1, EB-2, EB-3, EB-4, EB-5 (also 'Other Workers', 'Certain Religious Workers', or the EB-5 set-asides 'Rural' / 'High Unemployment' / 'Infrastructure').

## `country` (type: `string`):

The applicant's country of chargeability: worldwide (all other countries), China, India, Mexico, or Philippines. These are the only five columns the Visa Bulletin publishes.

## `dateType` (type: `string`):

final\_action = Final Action Dates (when a green card can actually be issued). dates\_for\_filing = Dates for Filing (when documents can be submitted). Most people want Final Action Dates.

## `priorityDate` (type: `string`):

The applicant's priority date, in YYYY-MM-DD format. When supplied, the result also says whether that date is current yet against this month's cutoff. Leave empty for a plain cutoff lookup.

## `month` (type: `string`):

Which Visa Bulletin to read: 'latest' (the current month, default), or a specific month like 'August 2026' or '2026-08'. Reference mode lists every available month.

## `targets` (type: `array`):

Check many category/country combinations in one run (cheaper and faster, because the browser session is shared). Each entry takes category and country, plus optional label, dateType and priorityDate.

## `monitorMode` (type: `boolean`):

Compare each target against the cutoff seen on the previous run and report only real movement: advancement (with the exact number of days), retrogression, or a category becoming Current or Unavailable. Schedule this monthly, the Visa Bulletin is republished monthly. The first run records a baseline.

## `watchlistId` (type: `string`):

Keeps separate monitor histories apart. Use a different ID per client list or per schedule so their baselines don't overwrite each other.

## `proxyConfiguration` (type: `object`):

travel.state.gov sits behind Cloudflare. The default (US residential) is the setting confirmed to work; change it only if you have a reason to.

## Actor input object example

```json
{
  "listAvailableOptions": false,
  "category": "EB-2",
  "country": "India",
  "dateType": "final_action",
  "priorityDate": "2019-03-15",
  "month": "latest",
  "targets": [
    {
      "label": "Client A - EB2 India",
      "category": "EB-2",
      "country": "India",
      "dateType": "final_action",
      "priorityDate": "2013-01-01"
    },
    {
      "label": "Client B - F2A Mexico",
      "category": "F2A",
      "country": "Mexico"
    }
  ],
  "monitorMode": false,
  "watchlistId": "default",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}
```

# Actor output Schema

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

No description

# 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 = {
    "category": "EB-2",
    "country": "India"
};

// Run the Actor and wait for it to finish
const run = await client.actor("nerolabs/us-visa-bulletin-monitor").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 = {
    "category": "EB-2",
    "country": "India",
}

# Run the Actor and wait for it to finish
run = client.actor("nerolabs/us-visa-bulletin-monitor").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 '{
  "category": "EB-2",
  "country": "India"
}' |
apify call nerolabs/us-visa-bulletin-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nerolabs/us-visa-bulletin-monitor"
        }
    }
}

```

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/q8vxrUzsO9ie2Tntw/builds/8Xiv5av8XxI9SX7rs/openapi.json