# Upwork Job Scraper - Job Alerts with Client Intel (`blackfalcondata/upwork-scraper`) Actor

Scrape Upwork jobs with full client intel — country, total spent, payment-verified, rating, reviews, exact applicant count. 14 filters, incremental mode that emits only new listings, and instant new-job alerts via Slack/Telegram/Discord/webhook.

- **URL**: https://apify.com/blackfalcondata/upwork-scraper.md
- **Developed by:** [Black Falcon Data](https://apify.com/blackfalcondata) (community)
- **Categories:** Jobs, Lead generation, Automation
- **Features:** Limited permissions
- **Stats:** 2,793 total users, 533 monthly users, 100.0% runs succeeded, 11 bookmarks
- **User rating**: 4.82 out of 5 stars

## Pricing

from $1.00 / 1,000 results

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?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

### What does Upwork Job Scraper do?

Upwork Scraper extracts structured job data from [upwork.com](https://upwork.com) with the full client-quality panel — client country, total spent, payment-verified status, rating, review count — plus the exact number of applicants per job (not tier-buckets) and engagement metadata. Works out of the box with no cookies or login. Paste an Upwork search URL or configure 14 filters directly. Incremental mode emits only new or changed listings on recurring runs.

### How to use this actor

- 👉 **Register for a free Apify account** — no credit card required.
- 🎉 Just click **[Sign up free on Apify →](https://console.apify.com/sign-up?fpr=1h3gvi)** and complete a quick signup.
- 💰 A free Apify account includes $5 in monthly credits — enough to test this actor.
- ⏳ Scrape during the free trial, with no commitment or upfront payment required.

### Key features

- **🏦 Client intelligence panel:** every job carries client country, lifetime spend, payment-verified flag, rating, and review count — qualify leads before spending a single Connect, with one-click minimum-spend, minimum-rating, and minimum-review filters.
- **💸 Connects-aware filter:** combine the `proposals` filter with incremental mode to surface low-competition listings the moment they're posted — before proposal counts (and Connect costs) climb.
- **🔗 Paste-mode:** paste any upwork.com URL straight from your browser — single-listing pages, search-results URLs, or category SEO URLs. Mix freely with keyword and IDs in the same run; results dedupe by ID.
- **🎯 Batch searches:** pass `["term1", "term2"]` for query, location, or city to batch multiple searches in one run — shared dedup state, single dataset, one Actor-Start charge instead of N.
- **📋 Detail enrichment:** toggle two-stage scraping: first collect listings, then enrich each with full description + detail-page-only fields. Off by default to keep runs fast; flip on when you need the deep payload.
- **♻️ Incremental mode:** recurring runs emit only new or changed projects since your last run — paste a `stateKey`, run hourly, never get the same lead twice. Saves 80–95% vs full re-scrapes.
- **🔔 Notifications:** push new-project alerts to Telegram / Slack / Discord / WhatsApp / webhook within seconds of posting — combine with incremental to never get duplicate alerts.
- **📦 Compact mode:** skinny output for outreach pipelines — just the fields your CRM or email tool reads. Drop straight into a Sheet without dragging unused columns.
- **✂️ Description truncation:** cap description length with `descriptionMaxLength` to control LLM prompt cost and dataset size — set 0 for full descriptions, or any char-limit to trim.
- **📤 Export anywhere:** Download the dataset as JSON, CSV, or Excel from the Apify Console, or stream live via the Apify API and integrations (Make, Zapier, Google Sheets, n8n, …).
- **🔌 MCP connectors:** export your results into Notion via Apify's MCP connectors — a clean run-summary page, no glue code. Opt-in via the App connector field; deterministic field-mapping, no AI. Built on Apify's connector framework, so more destinations open up as their catalog grows.

### What data can you extract from upwork.com?

Each result includes Core job fields (`jobId`, `title`, `jobType`, `experienceLevel`, `budgetAmount`, `budgetCurrency`, `hourlyBudgetMin`, and `hourlyBudgetMax`, and more) and extended fields (`description`, `descriptionHtml`, `descriptionMarkdown`, and `skillsDetailed`). In standard mode, all fields are always present — unavailable data points are returned as `null`, never omitted. In compact mode, only core fields are returned.

### Input

The main inputs are a search keyword, an optional location filter, and a result limit. Additional filters and options are available in the input schema.

Key parameters:

- **`query`** — Job search keywords. Leave empty to browse all jobs. Upwork matches ALL words; to match any of several terms, join them with OR (e.g. "human resources" OR handbook) — commas also mean AND.
- **`searchUrl`** — Paste a full Upwork search URL (https://www.upwork.com/nx/search/jobs/?q=...). Filters in the URL are auto-parsed; explicitly set input fields override URL values.
- **`jobType`** — Filter by payment type.
- **`experienceLevel`** — Filter by required experience.
- **`workload`** — Filter by time commitment.
- **`sort`** — How to sort results. (default: `"recency"`)
- **`category`** — Upwork category or subcategory name as shown on Upwork (e.g. "Accounting & Consulting", "Web Development"; case-insensitive; the homepage group labels "Development & IT", "Writing & Translation", "Admin & Customer Support" and "Finance & Accounting" also work and cover all their subcategories) or its numeric UID, or an array of either.
- **`location`** — Countries, regions, or structured entries. Accepts: country name ("United States"), ISO code ("US"), region name ("europe", "north_america", "english_speaking"), or {"type": "COUNTRY"|"REGION", "value": "..."}.
- **`excludeLocations`** — Countries or regions to exclude. Same format as location.
- **`budget`** — Filter fixed-price jobs by amount range (USD).
- **`hourlyRate`** — Filter hourly jobs by rate (USD/hr). Format: "min-max", open-ended with trailing dash ("50-").
- **`duration`** — Filter by expected length.
- ...and 41 more parameters

### Input examples

**Basic search** — Keyword-driven search with a result cap.

→ Full payload per result — all standard fields populated where the source provides them.

```json
{
  "query": "python developer",
  "maxResults": 50
}
```

**Filtered search** — Narrow results with advanced filters — only matching jobs are returned.

→ Same field set as basic search; fewer, more relevant rows.

```json
{
  "query": "python developer",
  "jobType": "hourly",
  "experienceLevel": "EntryLevel",
  "category": [
    "Accounting & Consulting"
  ],
  "maxResults": 100
}
```

**Incremental tracking** — Only emit jobs that changed since the previous run with this `stateKey`.

→ First run builds the baseline state. Subsequent runs emit only records that are new or whose tracked content changed. Set `emitUnchanged: true` to include unchanged records as well.

```json
{
  "query": "python developer",
  "maxResults": 200,
  "incrementalMode": true,
  "stateKey": "python-developer-tracker"
}
```

**Compact filtered output** — Combine filters with compact mode for a lightweight AI-agent or MCP data source.

→ Core fields only — ideal for piping into LLMs or downstream tools without token overhead.

```json
{
  "query": "python developer",
  "jobType": "hourly",
  "experienceLevel": "EntryLevel",
  "maxResults": 50,
  "compact": true
}
```

### Output

Each run produces a dataset of structured job records. Results can be downloaded as JSON, CSV, or Excel from the Dataset tab in Apify Console.

### Example job record

```json
{
  "jobId": "2047620102105297516",
  "title": "Full Stack Software Engineer Needed for Contract Work",
  "description": "Contract Software Engineer (AI Applications / High-Velocity Builder)\nLocation: Remote\nCompensation: $40–100/hour (contract)\nType: Project-based (20–60 hrs/week)\n\nAbout Us\nWe are a stealth AI company b...",
  "descriptionMarkdown": "Contract Software Engineer (AI Applications / High-Velocity Builder)\nLocation: Remote\nCompensation: $40–100/hour (contract)\nType: Project-based (20–60 hrs/week)\n\nAbout Us\nWe are a stealth AI company b...",
  "contentHash": "f6a9bbdcc53a7a571effa9c32e1d9008bea5c96d766c0d881b0818711568177a",
  "jobType": "HOURLY",
  "experienceLevel": "ExpertLevel",
  "hourlyBudgetMin": 40,
  "hourlyBudgetMax": 100,
  "engagementType": "FULL_TIME",
  "engagementDuration": "3 to 6 months",
  "engagementDurationWeeks": 18,
  "skills": [
    "JavaScript",
    "React",
    "Python",
    "API",
    "Web Development"
  ],
  "skillsDetailed": [
    {
      "uid": "996364628025274383",
      "name": "JavaScript",
      "highlighted": false
    },
    {
      "uid": "1031626773660942336",
      "name": "React",
      "highlighted": false
    },
    {
      "uid": "996364628025274386",
      "name": "Python",
      "highlighted": false
    },
    {
      "uid": "1110580482322976768",
      "name": "API",
      "highlighted": false
    },
    {
      "uid": "1031626795211276288",
      "name": "Web Development",
      "highlighted": false
    }
  ],
  "publishTime": "2026-04-24T10:15:12.253Z",
  "createTime": "2026-04-24T10:14:10.307Z",
  "totalApplicants": 58,
  "personsToHire": 50,
  "enterpriseJob": false,
  "premium": false,
  "clientCountry": "United States",
  "clientCountryCode": "USA",
  "clientTotalSpent": 5160.99,
  "clientSpentCurrency": "USD",
  "clientPaymentVerified": true,
  "clientRating": 5,
  "clientReviewCount": 4,
  "clientHasFinancialPrivacy": false,
  "customJobScore": 3.45,
  "url": "https://www.upwork.com/jobs/~022047620102105297516",
  "portalUrl": "https://www.upwork.com/jobs/~022047620102105297516",
  "scrapedAt": "2026-04-24T10:27:07.636Z",
  "source": "upwork.com",
  "isRepost": false
}
```

### Incremental fields

When incremental mode is on, each record also carries:

- `changeType` — one of `NEW`, `UPDATED`, `UNCHANGED`, `REAPPEARED`, `EXPIRED`. Default output covers `NEW` / `UPDATED` / `REAPPEARED`; set `emitUnchanged: true` or `emitExpired: true` to opt into the others.
- `isRepost`, `repostOfId`, `repostDetectedAt` — populated when a new listing matches the tracked content of a previously expired one. Set `skipReposts: true` to drop detected reposts from the output.

### How to scrape upwork.com

1. Go to [Upwork Job Scraper](https://apify.com/blackfalcondata/upwork-scraper?fpr=1h3gvi) in Apify Console.
2. Enter a search keyword and optional location filter.
3. Set `maxResults` to control how many results you need.
4. Click **Start** and wait for the run to finish.
5. Export the dataset as JSON, CSV, or Excel.

### Use cases

- Extract job data from upwork.com for market research and competitive analysis.
- Monitor new and changed jobs on scheduled runs without processing the full dataset every time.
- Feed structured data into AI agents, MCP tools, and automated pipelines using compact mode.
- Export clean, structured data to dashboards, spreadsheets, or data warehouses.
- Analyze skill demand across listings using structured skill tags.
- Collect ratings and reviews for reputation monitoring and benchmarking.

### How much does it cost to scrape upwork.com?

Upwork Job Scraper uses [pay-per-event](https://docs.apify.com/platform/actors/paid-actors/pay-per-event) pricing. You pay a small fee when the run starts and then for each result that is actually produced.

- **Run start:** $0.001 per run
- **Per result:** $0.001 per job record

Example costs:

- 10 results: **$0.011**
- 25 results: **$0.026**
- 100 results: **$0.1**
- 200 results: **$0.2**
- 500 results: **$0.5**

#### Example: recurring monitoring savings

These examples compare full re-scrapes with incremental runs at different churn rates. Churn is the share of jobs that are new or whose tracked content changed since the previous run. Actual churn depends on your query breadth, source activity, and polling frequency — the scenarios below are examples, not predictions.

Example setup: 250 jobs per run, daily polling (30 runs/month). Costs scale linearly with the number of jobs.

| Churn rate | Full re-scrape run cost | Incremental run cost | Savings vs full re-scrape | Monthly cost after baseline |
|---|---:|---:|---:|---:|
| 5% — stable niche query | $0.25 | $0.01 | $0.24 (95%) | $0.41 |
| 15% — moderate broad query | $0.25 | $0.04 | $0.21 (85%) | $1.16 |
| 30% — high-volume aggregator | $0.25 | $0.08 | $0.17 (70%) | $2.28 |

Full re-scrape monthly cost at the same cadence: $7.53. First month with incremental costs $0.64 / $1.37 / $2.45 for the 5% / 15% / 30% scenarios because the first run builds baseline state at full cost before incremental savings apply.

Platform usage is included in the per-result fee shown above.

### FAQ

#### How many results can I get from upwork.com?

The number of results depends on the search query and available jobs on upwork.com. Use the `maxResults` parameter to control how many results are returned per run.

#### Does Upwork Job Scraper support recurring monitoring?

Yes. Enable incremental mode to only receive new or changed jobs on subsequent runs. This is ideal for scheduled monitoring where you want to track changes over time without re-processing the full dataset.

#### Can I integrate Upwork Job Scraper with other apps?

Yes. Upwork Job Scraper works with Apify's [integrations](https://apify.com/integrations?fpr=1h3gvi) to connect with tools like Zapier, Make, Google Sheets, Slack, and more. You can also use webhooks to trigger actions when a run completes.

#### Can I use Upwork Job Scraper with the Apify API?

Yes. You can start runs, manage inputs, and retrieve results programmatically through the [Apify API](https://docs.apify.com/api/v2). Client libraries are available for JavaScript, Python, and other languages.

#### Can I use Upwork Job Scraper through an MCP Server?

Yes. Apify provides an [MCP Server](https://apify.com/apify/actors-mcp-server?fpr=1h3gvi) that lets AI assistants and agents call this actor directly. Use compact mode, `descriptionMaxLength`, a single `descriptionFormat`, and `excludeEmptyFields` to keep payloads manageable for LLM context windows.

#### Is it legal to scrape upwork.com?

This actor extracts publicly available data from upwork.com. Web scraping of public information is generally considered legal, but you should always review the target site's terms of service and ensure your use case complies with applicable laws and regulations, including GDPR where relevant.

#### Your feedback

If you have questions, need a feature, or found a bug, please [open an issue](https://apify.com/blackfalcondata/upwork-scraper/issues?fpr=1h3gvi) on the actor's page in Apify Console. Your feedback helps us improve.

### You might also like

- [Actiris Job Scraper \[Just 💰$1.5\] — Brussels Public Jobs](https://apify.com/blackfalcondata/actiris-scraper?fpr=1h3gvi) — 💰 $1.5 per 1,000 jobs. Scrape actiris.brussels — the official Brussels public employment service.
- [AMS Austria Job Scraper — Public Employment Service Jobs](https://apify.com/blackfalcondata/ams-austria-job-scraper?fpr=1h3gvi) — Scrape jobs.ams.at, Austria's official AMS public employment portal (alle jobs). Get live.
- [APEC Job Scraper \[Just 💰$0.8\] — French Executive Jobs](https://apify.com/blackfalcondata/apec-scraper?fpr=1h3gvi) — 💰 $0.8 per 1,000 jobs, platform usage included. Scrape apec.fr French executive listings — every.
- [Arbeitsagentur Job Scraper \[💰$0.45\] — German Federal Jobs](https://apify.com/blackfalcondata/arbeitsagentur-jobs-feed?fpr=1h3gvi) — 💰 from $0.45 per 1,000 jobs. Scrape arbeitsagentur.de — Germany's official public employment.
- [Arbetsförmedlingen \[Just 💰$3\] — Sweden Public Jobs](https://apify.com/blackfalcondata/arbetsformedlingen-scraper?fpr=1h3gvi) — 💰 $3 per 1,000 jobs. Scrape arbetsformedlingen.se (Platsbanken) — Sweden's official employment.
- [Bayt — MENA Jobs with Salary & Skills](https://apify.com/blackfalcondata/bayt-scraper?fpr=1h3gvi) — Scrape bayt.com — the leading Middle East job board across UAE · Saudi Arabia · Qatar · Egypt & 9.
- [Bayt Job Scraper — MENA Jobs with Salary & Skills](https://apify.com/blackfalcondata/bayt-scraper?fpr=1h3gvi) — Scrape bayt.com — the leading Middle East job board across UAE · Saudi Arabia · Qatar · Egypt & 9.
- [BestJobs.eu Scraper \[Just 💰$1.5\] — Romania Job Board](https://apify.com/blackfalcondata/bestjobs-eu-scraper?fpr=1h3gvi) — 💰 $1.5 per 1,000 jobs. Scrape bestjobs.eu — a leading Romanian job board — export salary ranges ·.

### Getting started with Apify

New to Apify? [Create a free account with $5 credit](https://console.apify.com/sign-up?fpr=1h3gvi) — no credit card required.

1. Sign up — $5 platform credit included
2. Open this actor and configure your input
3. Click **Start** — export results as JSON, CSV, or Excel

Need more later? [See Apify pricing](https://apify.com/pricing?fpr=1h3gvi).

### Disclaimer

This actor accesses only publicly available data on upwork.com. You are responsible for how you use the extracted data — in particular any personal information such as names, phone numbers, or email addresses — and for complying with Upwork's terms of use, applicable data-protection law (including the GDPR where it applies), and the anti-spam rules of your jurisdiction.

This actor is an independent tool and is not affiliated with, endorsed by, or sponsored by Upwork or any of its subsidiaries. All trademarks mentioned are the property of their respective owners.

### Search keywords

upwork scraper, upwork api, apify upwork, upwork data extraction, upwork.com scraper, upwork.com data, upwork.com api, job listings scraper, recruitment data, hiring data, job board scraper.

# Changelog

This Actor's version history is a separate document: https://apify.com/blackfalcondata/upwork-scraper/changelog.md

# Actor input Schema

## `query` (type: `string`):

Job search keywords. Leave empty to browse all jobs. Upwork matches ALL words; to match any of several terms, join them with OR (e.g. "human resources" OR handbook) — commas also mean AND.

## `searchUrl` (type: `string`):

Paste a full Upwork search URL (https://www.upwork.com/nx/search/jobs/?q=...). Filters in the URL are auto-parsed; explicitly set input fields override URL values.

## `jobType` (type: `string`):

Filter by payment type.

## `experienceLevel` (type: `string`):

Filter by required experience.

## `workload` (type: `string`):

Filter by time commitment.

## `sort` (type: `string`):

How to sort results.

## `category` (type: `array`):

Upwork category or subcategory name as shown on Upwork (e.g. "Accounting & Consulting", "Web Development"; case-insensitive; the homepage group labels "Development & IT", "Writing & Translation", "Admin & Customer Support" and "Finance & Accounting" also work and cover all their subcategories) or its numeric UID, or an array of either.

## `location` (type: `array`):

Countries, regions, or structured entries. Accepts: country name ("United States"), ISO code ("US"), region name ("europe", "north_america", "english_speaking"), or {"type": "COUNTRY"|"REGION", "value": "..."}.

## `excludeLocations` (type: `array`):

Countries or regions to exclude. Same format as location.

## `budget` (type: `string`):

Filter fixed-price jobs by amount range (USD).

## `hourlyRate` (type: `string`):

Filter hourly jobs by rate (USD/hr). Format: "min-max", open-ended with trailing dash ("50-").

## `duration` (type: `string`):

Filter by expected length.

## `verifiedPaymentOnly` (type: `boolean`):

Only show jobs from clients with a verified payment method.

## `proposals` (type: `string`):

Filter by number of proposals already submitted. Pick "0-4" for lowest competition.

## `contractToHire` (type: `boolean`):

Filter to jobs that may convert into a full-time hire.

## `clientHires` (type: `string`):

Filter by how many freelancers the client has hired.

## `includeKeywords` (type: `object`):

Require at least one of these keywords in title/description/skills. Example: {"keywords":\["React","Node.js"],"matchTitle":true,"matchDescription":true,"matchSkills":true}.

## `excludeKeywords` (type: `object`):

Exclude jobs containing any of these keywords. Same config shape as includeKeywords.

## `fromDate` (type: `string`):

Only include jobs published on or after this date. Accepts YYYY-MM-DD or ISO-8601.

## `toDate` (type: `string`):

Only include jobs published on or before this date.

## `maxAgeMinutes` (type: `integer`):

Only include jobs posted within the last N minutes. 0 = no limit. Pairs well with scheduled runs.

## `minClientTotalSpent` (type: `integer`):

Only include jobs from clients who have spent at least this much on Upwork.

## `minClientRating` (type: `number`):

Only include clients with a rating at least this high.

## `minClientReviewCount` (type: `integer`):

Only include clients with at least this many reviews.

## `customFilters` (type: `array`):

Array of rules applied to any output field. Each rule: {"field":"<name>","op":"includes|notIncludes|equals|notEquals|gt|gte|lt|lte","value":...}. Example: \[{"field":"clientCountry","op":"equals","value":"United States"}, {"field":"description","op":"notIncludes","value":"wordpress"}].

## `maxResults` (type: `integer`):

Maximum total results. 0 = unlimited. Upwork caps search depth at ~5050 results per query — narrow with filters for larger pools.

## `descriptionMaxLength` (type: `integer`):

Truncate description to N characters. 0 = full text.

## `compact` (type: `boolean`):

Core fields only — trimmed for LLM pipelines.

## `incrementalMode` (type: `boolean`):

Only output new/changed jobs since last run.

## `stateKey` (type: `string`):

Optional stable identifier for the tracked search universe. Leave empty to auto-derive a stable identifier from your search inputs — different keyword/location/filter combinations get isolated state automatically.

## `skipReposts` (type: `boolean`):

In incremental mode, skip jobs that appear to be reposts of previously-seen expired jobs (same content hash).

## `enrichDetails` (type: `boolean`):

Fetch the authenticated detail page per job to unlock ~30 extra fields: client timezone + city, industry, company size, total hires, hire rate, activity (totalHired, invites, last buyer activity), questions, attachments, allowed countries/English-level, min JSS, AI-generated description flag, work history with feedback. Each enriched job is billed as a separate PPE event. Pairs with incrementalMode to only enrich NEW/UPDATED jobs.

## `sessionToken` (type: `string`):

Bearer token from your logged-in Upwork session, used to unlock the detail-only fields. How to get it: (1) sign in at upwork.com, (2) open DevTools -> Network, (3) click any request to upwork.com, (4) under Request Headers copy the value of `authorization`, leaving out the leading "bearer ". The value looks like `oauth2v2_int_...`. Important: the cookie with a similar name carries a DIFFERENT token that has no access to these fields, so copying the cookie will not work. The token expires when your Upwork session refreshes, so a scheduled run needs it renewed periodically. Treat it as a password.

## `detailConcurrency` (type: `integer`):

Parallel requests when enriching. 5 is conservative; 10-20 works for small runs. Higher values increase risk of rate-limiting.

## `telegramToken` (type: `string`):

Telegram bot token from @BotFather. Send notifications to a chat or channel when new jobs are emitted. Pairs well with incrementalMode for real-time alerts.

## `telegramChatId` (type: `string`):

Chat ID (from @userinfobot) or channel ID (starts with -100 for channels). Required when telegramToken is set.

## `discordWebhookUrl` (type: `string`):

Discord channel webhook URL (Server Settings → Integrations → Webhooks → New Webhook). Sends rich embeds with title, budget, client, applicants, and score per job.

## `slackWebhookUrl` (type: `string`):

Slack incoming webhook URL (Slack App → Incoming Webhooks → Add New Webhook). Formats jobs as Slack blocks.

## `whatsappPhoneNumberId` (type: `string`):

WhatsApp Business phone number ID from Meta Business Manager (the numeric ID next to your number — NOT the phone number itself). Free service-conversation messages within 24 hours of last user-initiated contact.

## `whatsappAccessToken` (type: `string`):

Meta Cloud API access token with whatsapp_business_messaging scope. Get a permanent token from a system user in Meta Business Manager.

## `whatsappTo` (type: `string`):

Recipient phone number in E.164 format (e.g. +4512345678). The recipient must have messaged your business number within the last 24 hours.

## `webhookUrl` (type: `string`):

Universal escape hatch for n8n / Make / Zapier / custom HTTP backends. Receives a JSON POST { metadata, items } per run. Single attempt, 15 s timeout.

## `webhookHeaders` (type: `object`):

Additional HTTP headers sent with the generic webhook POST (e.g. {"Authorization":"Bearer ..."}).

## `notificationLimit` (type: `integer`):

Maximum number of jobs to send per notification batch. Prevents spam on large result sets.

## `notifyOnlyChanges` (type: `boolean`):

When Incremental Mode is on, only send notifications for NEW / UPDATED / REAPPEARED jobs. Has no effect outside incremental mode.

## `includeRunMetadata` (type: `boolean`):

Prepend a one-line summary (query + total count) to each notification batch.

## `descriptionFormat` (type: `string`):

Pick a single description representation. `all` keeps every variant; `text` / `html` / `markdown` drop the others.

## `excludeEmptyFields` (type: `boolean`):

Drop null, empty-string, and empty-array fields from each record before push. Smaller payloads for AI agents and dashboards.

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

Proxy configuration (optional). Leave on the default for best reliability.

## `appConnector` (type: `string`):

Optional. Pick a connected app under Settings → API & Integrations to receive your results. Notion is supported today (a run-summary page); other MCP connectors are best-effort as Apify expands its catalog.

## `mcpIssueTeam` (type: `string`):

Only when the connected app is an issue tracker: the team (name or ID) the summary issue is created under, if that app requires one.

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

One or more Upwork job SEARCH URLs — run the search you want on upwork.com and copy the address bar. Each URL is searched separately and the results are merged and de-duplicated, so this is the way to cover several searches in one run. The filters in each URL apply to that URL alone; any filter you also set in the fields below applies to every URL and wins over the URL's own value. Links to a single job posting are not supported here and will stop the run.

## `emitUnchanged` (type: `boolean`):

When incremental mode is on, also emit listings whose content has not changed since the last run.

## `emitExpired` (type: `boolean`):

When incremental mode is on, also emit listings that were seen before but are no longer found.

## Actor input object example

```json
{
  "query": "python developer",
  "sort": "recency",
  "verifiedPaymentOnly": false,
  "contractToHire": false,
  "maxAgeMinutes": 0,
  "minClientTotalSpent": 0,
  "minClientRating": 0,
  "minClientReviewCount": 0,
  "maxResults": 100,
  "descriptionMaxLength": 0,
  "compact": false,
  "incrementalMode": false,
  "skipReposts": false,
  "enrichDetails": false,
  "detailConcurrency": 5,
  "notificationLimit": 5,
  "notifyOnlyChanges": false,
  "includeRunMetadata": true,
  "descriptionFormat": "all",
  "excludeEmptyFields": false,
  "proxyConfiguration": {
    "useApifyProxy": true
  },
  "emitUnchanged": false,
  "emitExpired": false
}
```

# Actor output Schema

## `results` (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 = {
    "query": "python developer",
    "maxResults": 100,
    "descriptionFormat": "all",
    "excludeEmptyFields": false,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("blackfalcondata/upwork-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 = {
    "query": "python developer",
    "maxResults": 100,
    "descriptionFormat": "all",
    "excludeEmptyFields": False,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("blackfalcondata/upwork-scraper").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 '{
  "query": "python developer",
  "maxResults": 100,
  "descriptionFormat": "all",
  "excludeEmptyFields": false,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call blackfalcondata/upwork-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,blackfalcondata/upwork-scraper"
        }
    }
}
```

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/FlbDgNCfA8bOdFQWT/builds/3RzQdpKbK01apc9ca/openapi.json