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

Scrape Upwork jobs with full client intelligence — country, total spent, payment-verified, rating, reviews, and exact applicant count. 14 filters and incremental mode that emits only new or changed listings across runs.

- **URL**: https://apify.com/blackfalcondata/upwork-scraper.md
- **Developed by:** [Black Falcon Data](https://apify.com/blackfalcondata) (community)
- **Categories:** Jobs, Lead generation, Automation
- **Stats:** 195 total users, 88 monthly users, 94.6% runs succeeded, 3 bookmarks
- **User rating**: 5.00 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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.md):

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

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.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/platform/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

### What does Upwork 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.

**New to Apify?** [Sign up free](https://console.apify.com/sign-up?fpr=1h3gvi) and use the included $5 monthly platform credit to test this actor.

### Key features

- **Client intelligence on every job** — country, lifetime spend, payment-verified flag, rating, review count, and financial-privacy signal, so you can qualify leads before spending a single Connect.
- **Exact applicant count** — precise integer per listing, not tier-buckets like "20-49". Combine with the `proposals` filter to find low-competition jobs the moment they're posted.
- **14 filters out of the box** — category, country or region, fixed-price budget range, hourly-rate range, project duration, payment-verified-only, proposals-range, contract-to-hire, experience level, workload, client-hires history, job type, sort order, and keyword.
- **Client-quality gates** — minimum client total spent, minimum rating, minimum review count as one-click filters. Layer them on top of the custom-filter DSL (`includes` / `equals` / `gte` / `lt` operators on any of 30+ fields).
- **Incremental mode** — recurring runs emit and charge only for listings that are new or whose tracked content changed. Paste a `stateKey`, run daily, pay for the diff.
- **Repost detection** — content-hash matching flags reposts of previously expired listings across runs. Filter them out with `skipReposts: true`.
- **Paste a search URL** — `searchUrl` accepts any `upwork.com/nx/search/jobs/?q=...` URL; all query-params auto-parse into filters. Explicit input fields override URL values.
- **Composite job-quality score** (`customJobScore`) — a 0–5 rating computed transparently from payment verification, client rating, review reliability, and lifetime spend. Sort or threshold by it.
- **Rich post-fetch filters** — include / exclude keywords with independent title / description / skills toggles, publish-time `fromDate` / `toDate`, `maxAgeMinutes` for real-time alerts, and region-grouped location filters (Europe, North America, English-speaking, etc.).
- **Detail enrichment** (optional addon) — supply your own Upwork session cookie to unlock ~30 extra fields: client timezone, city, industry, company size, total hires, hire-rate, activity panel, screening questions, attachments, work history with bi-directional feedback, allowed countries, AI-generated-description flag, and more.
- **Notifications built in** — Telegram, Discord, Slack, WhatsApp, and generic webhook support. Fire on new matching jobs without setting up a separate pipeline. Pairs with `incrementalMode` so you never get the same alert twice.
- **LLM-ready** — `compact` mode trims to core fields for MCP / agent context. `descriptionMaxLength` caps long briefs so they fit in a prompt window.
- **Country normalisation** — all `clientCountry` values returned as canonical names, plus a separate `clientCountryCode` ISO-3 field for cross-source joins.
- **Zero setup** — no cookies, logins, or manual configuration required. The optional detail-enrichment addon can unlock ~30 extra fields when you supply your own Upwork session.

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

Each result includes Core listing fields (`jobId`, `title`, `jobType`, `experienceLevel`, `budgetAmount`, `budgetCurrency`, `hourlyBudgetMin`, and `hourlyBudgetMax`, and more) and detail fields when enrichment is enabled (`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.
- **`searchUrl`** — Paste a full Upwork search URL (https://www.upwork.com/nx/search/jobs/?q=...). Filters in the URL are auto-parsed and override individual fields.
- **`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 name (e.g. "Web Development") or category2 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 28 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": [
    "Web Development"
  ],
  "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; unchanged records are skipped.

```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...",
  "descriptionHtml": null,
  "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",
  "budgetAmount": null,
  "budgetCurrency": null,
  "hourlyBudgetMin": 40,
  "hourlyBudgetMax": 100,
  "weeklyRetainerBudget": null,
  "engagementType": "FULL_TIME",
  "engagementDuration": "3 to 6 months",
  "engagementDurationWeeks": 18,
  "skills": [
    "JavaScript",
    "React",
    "Python",
    "API",
    "Web Development"
  ],
  "skillsDetailed": [
    {
      "uid": "996364628025274383",
      "parentSkillUid": null,
      "name": "JavaScript",
      "highlighted": false
    },
    {
      "uid": "1031626773660942336",
      "parentSkillUid": null,
      "name": "React",
      "highlighted": false
    },
    {
      "uid": "996364628025274386",
      "parentSkillUid": null,
      "name": "Python",
      "highlighted": false
    },
    {
      "uid": "1110580482322976768",
      "parentSkillUid": null,
      "name": "API",
      "highlighted": false
    },
    {
      "uid": "1031626795211276288",
      "parentSkillUid": null,
      "name": "Web Development",
      "highlighted": false
    }
  ],
  "publishTime": "2026-04-24T10:15:12.253Z",
  "createTime": "2026-04-24T10:14:10.307Z",
  "sourcingTimestamp": null,
  "totalApplicants": 58,
  "personsToHire": 50,
  "enterpriseJob": false,
  "premium": false
}
```

### Incremental fields

When `incremental: true`, each record also carries:

- `changeType` — one of `NEW`, `UPDATED`, `UNCHANGED`, `REAPPEARED`, `EXPIRED`.
- `firstSeenAt`, `lastSeenAt` — ISO-8601 timestamps tracking the listing across runs.
- `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 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 listings 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 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.01**
- 100 results: **$0.1**
- 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 listings 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: 200 results per run, daily polling (30 runs/month). Event-pricing examples scale linearly with result count.

Numbers below are for the primary **Result** event. Other events (**Detail Enrichment (addon)**) are billed separately when they fire and follow the same incremental logic — when the underlying record has not changed, no charge is emitted.

| Churn rate | Full re-scrape run cost | Incremental run cost | Savings vs full re-scrape | Monthly cost after baseline |
|---|---:|---:|---:|---:|
| 5% — stable niche query | $0.20 | $0.01 | $0.19 (95%) | $0.33 |
| 15% — moderate broad query | $0.20 | $0.03 | $0.17 (85%) | $0.93 |
| 30% — high-volume aggregator | $0.20 | $0.06 | $0.14 (70%) | $1.83 |

Full re-scrape monthly cost at daily polling: $6.03. First month with incremental costs $0.52 / $1.10 / $1.97 for the 5% / 15% / 30% scenarios because the first run builds baseline state at full cost before incremental savings apply.

### FAQ

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

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

#### Does Upwork Scraper support recurring monitoring?

Yes. Enable incremental mode to only receive new or changed listings 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 Scraper with other apps?

Yes. Upwork Scraper has built-in notification channels — Telegram, Discord, Slack, WhatsApp (Meta Cloud API), and a generic JSON webhook (for n8n, Make, Zapier, or any custom HTTP backend). Configure one or more channels in the input and notifications fire at the end of every run. Combine with `incrementalMode` and `notifyOnlyChanges` to receive alerts only for new or updated listings. It also works with Apify's [integrations](https://apify.com/integrations?fpr=1h3gvi) to push data to Google Sheets, data warehouses, and more.

#### Can I use Upwork 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 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 and `descriptionMaxLength` 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 Brussels Job Scraper](https://apify.com/blackfalcondata/actiris-scraper?fpr=1h3gvi) — Scrape all active job listings from actiris.brussels — official Brussels public employment service..
- [Adzuna Job Scraper](https://apify.com/blackfalcondata/adzuna-scraper?fpr=1h3gvi) — Scrape adzuna.com - the global job board with 20+ country markets. Structured salary.
- [APEC.fr Scraper - French Executive Jobs](https://apify.com/blackfalcondata/apec-scraper?fpr=1h3gvi) — Scrape apec.fr - French executive job listings with salary ranges, company, location, skills,.
- [Arbeitsagentur Scraper - German Jobs](https://apify.com/blackfalcondata/arbeitsagentur-scraper?fpr=1h3gvi) — Scrape arbeitsagentur.de - Germany’s official employment portal with 1M+ listings. Contact data,.
- [Arbetsformedlingen Job Scraper](https://apify.com/blackfalcondata/arbetsformedlingen-scraper?fpr=1h3gvi) — Scrape arbetsformedlingen.se (Platsbanken) — Sweden's official employment portal. Returns 84.
- [AutoScout24 Scraper](https://apify.com/blackfalcondata/autoscout24-scraper?fpr=1h3gvi) — Scrape autoscout24.com - Europe's largest used car marketplace with 770K+ listings. Structured.
- [Bayt.com Scraper - Jobs from the Middle East](https://apify.com/blackfalcondata/bayt-scraper?fpr=1h3gvi) — Scrape bayt.com - the leading Middle East job board. Salary data, experience requirements.
- [Bilbasen Scraper - Denmark’s Car Marketplace](https://apify.com/blackfalcondata/bilbasen-scraper?fpr=1h3gvi) — Scrape bilbasen.dk - Denmark’s largest car marketplace. Full vehicle specifications, seller.

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

# Actor input Schema

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

Job search keywords. Leave empty to browse all jobs.

## `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 name (e.g. "Web Development") or category2 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`):

JWT Bearer token from the `oauth2_global_js_token` cookie in your logged-in Upwork session. MUST start with 'eyJ...' — tokens in the 'oauth2v2\_int\_XXXX' format are issued by the visitor OAuth2 client and DO NOT have scope for detail-page fields, so they will be rejected with field-permission errors. How to get the right token: (1) log in to upwork.com, (2) DevTools → Application → Cookies → upwork.com, (3) find cookie named `oauth2_global_js_token`, (4) copy its Value (long JWT starting with 'eyJ...'). Typically lives 24h. Treat 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.

## Actor input object example

```json
{
  "query": "python developer",
  "sort": "recency",
  "verifiedPaymentOnly": false,
  "contractToHire": false,
  "maxAgeMinutes": 0,
  "minClientTotalSpent": 0,
  "minClientRating": 0,
  "minClientReviewCount": 0,
  "maxResults": 10,
  "descriptionMaxLength": 0,
  "compact": false,
  "incrementalMode": false,
  "skipReposts": false,
  "enrichDetails": false,
  "detailConcurrency": 5,
  "notificationLimit": 5,
  "notifyOnlyChanges": false,
  "includeRunMetadata": true,
  "descriptionFormat": "all",
  "excludeEmptyFields": 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": 10,
    "descriptionFormat": "all",
    "excludeEmptyFields": false
};

// 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": 10,
    "descriptionFormat": "all",
    "excludeEmptyFields": False,
}

# 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("💾 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 '{
  "query": "python developer",
  "maxResults": 10,
  "descriptionFormat": "all",
  "excludeEmptyFields": false
}' |
apify call blackfalcondata/upwork-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Upwork Scraper - Freelance Job Listings with Client Intel",
        "description": "Scrape Upwork jobs with full client intelligence — country, total spent, payment-verified, rating, reviews, and exact applicant count. 14 filters and incremental mode that emits only new or changed listings across runs.",
        "version": "0.6",
        "x-build-id": "GvGbAULjjJncaYWyc"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/blackfalcondata~upwork-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-blackfalcondata-upwork-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/blackfalcondata~upwork-scraper/runs": {
            "post": {
                "operationId": "runs-sync-blackfalcondata-upwork-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/blackfalcondata~upwork-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-blackfalcondata-upwork-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": {
                    "query": {
                        "title": "🔍 Search Term(s)",
                        "type": "string",
                        "description": "Job search keywords. Leave empty to browse all jobs."
                    },
                    "searchUrl": {
                        "title": "🔗 Search URL",
                        "type": "string",
                        "description": "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": {
                        "title": "💼 Job Type",
                        "enum": [
                            "hourly",
                            "fixed"
                        ],
                        "type": "string",
                        "description": "Filter by payment type."
                    },
                    "experienceLevel": {
                        "title": "🎓 Experience Level",
                        "enum": [
                            "EntryLevel",
                            "IntermediateLevel",
                            "ExpertLevel"
                        ],
                        "type": "string",
                        "description": "Filter by required experience."
                    },
                    "workload": {
                        "title": "⏳ Workload",
                        "enum": [
                            "as_needed",
                            "part_time",
                            "full_time"
                        ],
                        "type": "string",
                        "description": "Filter by time commitment."
                    },
                    "sort": {
                        "title": "🔀 Sort Order",
                        "enum": [
                            "recency",
                            "relevance",
                            "newest",
                            "oldest"
                        ],
                        "type": "string",
                        "description": "How to sort results.",
                        "default": "recency"
                    },
                    "category": {
                        "title": "📁 Category",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Upwork category name (e.g. \"Web Development\") or category2 UID, or an array of either.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "location": {
                        "title": "🌍 Client Location (include)",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "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": {
                        "title": "🚫 Client Location (exclude)",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Countries or regions to exclude. Same format as location."
                    },
                    "budget": {
                        "title": "💰 Fixed-Price Budget Range",
                        "enum": [
                            "0-99",
                            "100-499",
                            "500-999",
                            "1000-4999",
                            "5000-"
                        ],
                        "type": "string",
                        "description": "Filter fixed-price jobs by amount range (USD)."
                    },
                    "hourlyRate": {
                        "title": "⏱️ Hourly Rate Range",
                        "type": "string",
                        "description": "Filter hourly jobs by rate (USD/hr). Format: \"min-max\", open-ended with trailing dash (\"50-\")."
                    },
                    "duration": {
                        "title": "📅 Project Duration",
                        "enum": [
                            "week",
                            "month",
                            "semester",
                            "ongoing"
                        ],
                        "type": "string",
                        "description": "Filter by expected length."
                    },
                    "verifiedPaymentOnly": {
                        "title": "✅ Payment-Verified Clients Only",
                        "type": "boolean",
                        "description": "Only show jobs from clients with a verified payment method.",
                        "default": false
                    },
                    "proposals": {
                        "title": "📊 Proposals Count (competition level)",
                        "enum": [
                            "0-4",
                            "5-9",
                            "10-14",
                            "15-19",
                            "20-49"
                        ],
                        "type": "string",
                        "description": "Filter by number of proposals already submitted. Pick \"0-4\" for lowest competition."
                    },
                    "contractToHire": {
                        "title": "🤝 Contract-to-Hire Only",
                        "type": "boolean",
                        "description": "Filter to jobs that may convert into a full-time hire.",
                        "default": false
                    },
                    "clientHires": {
                        "title": "📋 Client Hiring History",
                        "enum": [
                            "0",
                            "1-9",
                            "10+"
                        ],
                        "type": "string",
                        "description": "Filter by how many freelancers the client has hired."
                    },
                    "includeKeywords": {
                        "title": "📝 Include Keywords",
                        "type": "object",
                        "description": "Require at least one of these keywords in title/description/skills. Example: {\"keywords\":[\"React\",\"Node.js\"],\"matchTitle\":true,\"matchDescription\":true,\"matchSkills\":true}."
                    },
                    "excludeKeywords": {
                        "title": "🚫 Exclude Keywords",
                        "type": "object",
                        "description": "Exclude jobs containing any of these keywords. Same config shape as includeKeywords."
                    },
                    "fromDate": {
                        "title": "📅 From Date",
                        "type": "string",
                        "description": "Only include jobs published on or after this date. Accepts YYYY-MM-DD or ISO-8601."
                    },
                    "toDate": {
                        "title": "📅 To Date",
                        "type": "string",
                        "description": "Only include jobs published on or before this date."
                    },
                    "maxAgeMinutes": {
                        "title": "⏰ Max Age (minutes)",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Only include jobs posted within the last N minutes. 0 = no limit. Pairs well with scheduled runs.",
                        "default": 0
                    },
                    "minClientTotalSpent": {
                        "title": "💵 Min Client Total Spent (USD)",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Only include jobs from clients who have spent at least this much on Upwork.",
                        "default": 0
                    },
                    "minClientRating": {
                        "title": "⭐ Min Client Rating (0-5)",
                        "minimum": 0,
                        "maximum": 5,
                        "type": "number",
                        "description": "Only include clients with a rating at least this high.",
                        "default": 0
                    },
                    "minClientReviewCount": {
                        "title": "🗂️ Min Client Review Count",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Only include clients with at least this many reviews.",
                        "default": 0
                    },
                    "customFilters": {
                        "title": "🔧 Custom Filters (advanced)",
                        "type": "array",
                        "description": "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": {
                        "title": "💯 Max Results",
                        "minimum": 0,
                        "maximum": 5050,
                        "type": "integer",
                        "description": "Maximum total results. 0 = unlimited. Upwork caps search depth at ~5050 results per query — narrow with filters for larger pools.",
                        "default": 50
                    },
                    "descriptionMaxLength": {
                        "title": "✂️ Description Max Length",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Truncate description to N characters. 0 = full text.",
                        "default": 0
                    },
                    "compact": {
                        "title": "📦 Compact Output (for AI/MCP)",
                        "type": "boolean",
                        "description": "Core fields only — trimmed for LLM pipelines.",
                        "default": false
                    },
                    "incrementalMode": {
                        "title": "♻️ Incremental Mode",
                        "type": "boolean",
                        "description": "Only output new/changed jobs since last run.",
                        "default": false
                    },
                    "stateKey": {
                        "title": "🔑 State Key",
                        "type": "string",
                        "description": "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": {
                        "title": "🚫 Skip Reposts",
                        "type": "boolean",
                        "description": "In incremental mode, skip jobs that appear to be reposts of previously-seen expired jobs (same content hash).",
                        "default": false
                    },
                    "enrichDetails": {
                        "title": "💎 Enrich With Details (requires session token)",
                        "type": "boolean",
                        "description": "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.",
                        "default": false
                    },
                    "sessionToken": {
                        "title": "🔐 Upwork Session Token",
                        "type": "string",
                        "description": "JWT Bearer token from the `oauth2_global_js_token` cookie in your logged-in Upwork session. MUST start with 'eyJ...' — tokens in the 'oauth2v2_int_XXXX' format are issued by the visitor OAuth2 client and DO NOT have scope for detail-page fields, so they will be rejected with field-permission errors. How to get the right token: (1) log in to upwork.com, (2) DevTools → Application → Cookies → upwork.com, (3) find cookie named `oauth2_global_js_token`, (4) copy its Value (long JWT starting with 'eyJ...'). Typically lives 24h. Treat as a password."
                    },
                    "detailConcurrency": {
                        "title": "⚙️ Detail Fetch Concurrency",
                        "minimum": 1,
                        "maximum": 30,
                        "type": "integer",
                        "description": "Parallel requests when enriching. 5 is conservative; 10-20 works for small runs. Higher values increase risk of rate-limiting.",
                        "default": 5
                    },
                    "telegramToken": {
                        "title": "📱 Telegram Bot Token",
                        "type": "string",
                        "description": "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": {
                        "title": "💬 Telegram Chat / Channel ID",
                        "type": "string",
                        "description": "Chat ID (from @userinfobot) or channel ID (starts with -100 for channels). Required when telegramToken is set."
                    },
                    "discordWebhookUrl": {
                        "title": "💬 Discord Webhook URL",
                        "type": "string",
                        "description": "Discord channel webhook URL (Server Settings → Integrations → Webhooks → New Webhook). Sends rich embeds with title, budget, client, applicants, and score per job."
                    },
                    "slackWebhookUrl": {
                        "title": "💼 Slack Incoming Webhook URL",
                        "type": "string",
                        "description": "Slack incoming webhook URL (Slack App → Incoming Webhooks → Add New Webhook). Formats jobs as Slack blocks."
                    },
                    "whatsappPhoneNumberId": {
                        "title": "📱 WhatsApp Phone Number ID",
                        "type": "string",
                        "description": "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": {
                        "title": "🔐 WhatsApp Access Token",
                        "type": "string",
                        "description": "Meta Cloud API access token with whatsapp_business_messaging scope. Get a permanent token from a system user in Meta Business Manager."
                    },
                    "whatsappTo": {
                        "title": "📨 WhatsApp Recipient",
                        "type": "string",
                        "description": "Recipient phone number in E.164 format (e.g. +4512345678). The recipient must have messaged your business number within the last 24 hours."
                    },
                    "webhookUrl": {
                        "title": "🪝 Generic Webhook URL",
                        "type": "string",
                        "description": "Universal escape hatch for n8n / Make / Zapier / custom HTTP backends. Receives a JSON POST { metadata, items } per run. Single attempt, 15 s timeout."
                    },
                    "webhookHeaders": {
                        "title": "🪝 Webhook Headers (optional)",
                        "type": "object",
                        "description": "Additional HTTP headers sent with the generic webhook POST (e.g. {\"Authorization\":\"Bearer ...\"})."
                    },
                    "notificationLimit": {
                        "title": "🔢 Notification Limit",
                        "minimum": 1,
                        "maximum": 20,
                        "type": "integer",
                        "description": "Maximum number of jobs to send per notification batch. Prevents spam on large result sets.",
                        "default": 5
                    },
                    "notifyOnlyChanges": {
                        "title": "🔔 Notify Only New/Updated Jobs",
                        "type": "boolean",
                        "description": "When Incremental Mode is on, only send notifications for NEW / UPDATED / REAPPEARED jobs. Has no effect outside incremental mode.",
                        "default": false
                    },
                    "includeRunMetadata": {
                        "title": "📣 Include Run Summary in Notifications",
                        "type": "boolean",
                        "description": "Prepend a one-line summary (query + total count) to each notification batch.",
                        "default": true
                    },
                    "descriptionFormat": {
                        "title": "Description format",
                        "enum": [
                            "all",
                            "text",
                            "html",
                            "markdown"
                        ],
                        "type": "string",
                        "description": "Pick a single description representation. `all` keeps every variant; `text` / `html` / `markdown` drop the others.",
                        "default": "all"
                    },
                    "excludeEmptyFields": {
                        "title": "Exclude empty fields from output",
                        "type": "boolean",
                        "description": "Drop null, empty-string, and empty-array fields from each record before push. Smaller payloads for AI agents and dashboards.",
                        "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```