Examples
Real-world examples showing how to use Upwork Job Search MCP. Each example includes the full JSON input you can pass to search_jobs, along with a description of the use case and expected results.
Tip: You do not need to write JSON manually. Just describe what you want in natural language to your AI assistant, and it will construct the correct search_jobs call for you.
Minimal Example
The simplest possible search. Returns the 100 most recently posted jobs with no filters. Great for verifying your setup works.
search_jobs input
{
"limit": 100
}Expected: Returns up to 100 jobs sorted by most recent. No filters applied.
Daily Freelancer Monitor
Search for jobs posted in the last 24 hours matching your skills, minimum hourly rate, and client quality. Run this daily to catch new opportunities.
search_jobs input
{
"limit": 1000,
"searchPeriod": "24h",
"jobCategories": ["Web Development", "Mobile Development"],
"includeKeywords": {
"keywords": ["React", "TypeScript", "Next.js"],
"matchTitle": true,
"matchDescription": true,
"matchSkills": true
},
"budget": {
"hourlyRate": {
"min": "60"
}
},
"client": {
"paymentMethodVerified": true,
"minFeedbackScore": "4.0",
"totalSpent": {
"min": "10000"
}
},
"vendor": {
"experienceLevel": ["INTERMEDIATE", "EXPERT"]
}
}Expected: Typically returns 20-50 jobs per day depending on market activity.
Agency Market Analysis
Find high-budget fixed-price projects from experienced clients. Useful for agencies looking to identify premium opportunities and analyze market pricing.
search_jobs input
{
"limit": 500,
"searchPeriod": "7d",
"jobCategories": [
"Web Development",
"Mobile Development",
"AI/ML Engineering"
],
"budget": {
"fixedPrice": {
"min": "10000"
},
"jobDurations": [
"UP_TO_THREE_MONTHS",
"UP_TO_SIX_MONTHS",
"MORE_THAN_SIX_MONTHS"
]
},
"client": {
"paymentMethodVerified": true,
"totalSpent": {
"min": "100000"
},
"minFeedbackScore": "4.5",
"includeLocations": [
{ "type": "COUNTRY", "value": "US" },
{ "type": "COUNTRY", "value": "GB" },
{ "type": "COUNTRY", "value": "CA" },
{ "type": "COUNTRY", "value": "AU" }
]
},
"vendor": {
"experienceLevel": ["EXPERT"],
"type": ["FREELANCER", "AGENCY"]
}
}Expected: Returns 5-20 premium opportunities per week from top-tier clients.
Advanced Filtering
Combine include and exclude keyword filters with budget, client, and vendor requirements for highly targeted results.
search_jobs input
{
"limit": 2000,
"searchPeriod": "14d",
"jobCategories": ["Web Development"],
"includeKeywords": {
"keywords": ["React", "Vue", "Angular", "TypeScript"],
"matchTitle": true,
"matchDescription": true,
"matchSkills": true
},
"excludeKeywords": {
"keywords": ["WordPress", "Shopify", "Wix", "intern"],
"matchTitle": true,
"matchDescription": true
},
"budget": {
"hourlyRate": {
"min": "50",
"max": "200"
},
"connectsPrice": {
"max": 16
},
"minClientHireRate": 50,
"allowUnspecifiedBudget": false,
"hourlyWorkloads": ["MORE_THAN_30_HOURS"]
},
"client": {
"paymentMethodVerified": true,
"phoneNumberVerified": true,
"minFeedbackScore": "4.0",
"totalSpent": {
"min": "5000"
},
"excludeLocations": [
{ "type": "COUNTRY", "value": "IN" },
{ "type": "COUNTRY", "value": "PK" }
],
"includeWithNoFeedback": false
},
"vendor": {
"experienceLevel": ["INTERMEDIATE", "EXPERT"],
"englishProficiency": "FLUENT",
"excludeWithQuestions": false
}
}Expected: Highly targeted search with 15+ filters. Expect 30-80 results over 14 days.
Real-Time Monitoring with Notifications
Set up continuous monitoring with Telegram, Discord, or Slack notifications. Use searchPeriod with overlap for gapless coverage.
search_jobs input
{
"limit": 500,
"searchPeriod": "1h",
"jobCategories": [
"Web Development",
"AI/ML Engineering",
"Data Science"
],
"includeKeywords": {
"keywords": ["Python", "React", "LLM", "AI"],
"matchTitle": true,
"matchSkills": true
},
"budget": {
"hourlyRate": {
"min": "60"
}
},
"client": {
"paymentMethodVerified": true,
"totalSpent": {
"min": "5000"
}
}
}Expected: Run every 45 minutes with 15 minutes of overlap to avoid missing jobs during refresh windows. Pair with Telegram, Discord, or Slack webhooks for instant alerts.
Client Quality Deep Dive
First search for jobs, then use premium tools to evaluate the best matches. Check how many proposals a job has received and review the client's past work history.
search_jobs input
// Step 1: Search for matching jobs
{
"limit": 50,
"searchPeriod": "24h",
"jobCategories": ["Web Development"],
"budget": {
"hourlyRate": { "min": "80" }
},
"client": {
"paymentMethodVerified": true,
"totalSpent": { "min": "50000" }
}
}
// Step 2: For each promising job, check activity
// get_client_activity({ "jobId": "1955020056847176693" })
// Returns: proposalCount, lastClientActivity, interviewingCandidates
// Step 3: Check client history for top picks
// get_client_history({ "jobId": "1955020056847176693" })
// Returns: past contracts, ratings, feedback from freelancersExpected: Premium tools consume credit at $5.40/1k results returned. Use them selectively on your top 5-10 candidates to keep costs low.
Try a real example
These recipes run end-to-end against the same API. Copy and adapt.