Getting Started Setup Authentication REST API Tool Reference Examples Integrations Job Categories Locations Rate Limits Billing Webhooks Troubleshooting

Tool Reference

Complete reference for all 4 MCP tools. Each tool is called automatically by your AI assistant based on your natural language queries.

search_jobs get_job get_client_activity get_client_history

search_jobs

Search Upwork jobs with 40+ filters across 5 categories. Returns an array of matching jobs with full details including client stats, budget, skills, and direct Upwork links.

Basic Settings

Parameter	Type	Description	Example
`limit`	integer	Maximum number of jobs to return(1-10,000)	`1000`
`searchPeriod`	string	Relative time window for job search("1h", "6h", "24h", "7d", "14d", "30d")	`"24h"`
`fromDate`	string (ISO)	Start of date range (ISO 8601)(Any valid date)	`"2025-01-01"`
`toDate`	string (ISO)	End of date range (ISO 8601)(Any valid date)	`"2025-12-31"`
`jobCategories`	string[]	Filter by Upwork job categories(See Categories page)	`["Web Development"]`

Keyword Filters

Parameter	Type	Description	Example
`includeKeywords.keywords`	string[]	Terms that must appear in the job	`["React", "TypeScript"]`
`includeKeywords.matchTitle`	boolean	Match keywords against job title	`true`
`includeKeywords.matchDescription`	boolean	Match keywords against job description	`true`
`includeKeywords.matchSkills`	boolean	Match keywords against required skills	`true`
`excludeKeywords.keywords`	string[]	Terms to exclude from results	`["WordPress", "Shopify"]`
`excludeKeywords.matchTitle`	boolean	Exclude from title matches	`true`
`excludeKeywords.matchDescription`	boolean	Exclude from description matches	`true`
`excludeKeywords.matchSkills`	boolean	Exclude from skill matches	`true`

Budget & Payment

Parameter	Type	Description	Example
`budget.hourlyRate.min`	string (USD)	Minimum hourly rate	`"50"`
`budget.hourlyRate.max`	string (USD)	Maximum hourly rate	`"200"`
`budget.fixedPrice.min`	string (USD)	Minimum fixed-price budget	`"1000"`
`budget.fixedPrice.max`	string (USD)	Maximum fixed-price budget	`"50000"`
`budget.connectsPrice.min`	integer	Minimum application cost in connects	`4`
`budget.connectsPrice.max`	integer	Maximum application cost in connects	`16`
`budget.jobDurations`	string[]	Filter by project duration	`["UP_TO_THREE_MONTHS"]`
`budget.hourlyWorkloads`	string[]	Filter by weekly hours	`["MORE_THAN_30_HOURS"]`
`budget.minClientHireRate`	integer	Minimum client hire rate percentage	`50`
`budget.allowUnspecifiedBudget`	boolean	Include jobs with no budget specified	`false`
`budget.onlyContractToHire`	boolean	Only contract-to-hire positions	`true`
`budget.noHireRate`	boolean	Include clients with no hire rate data	`false`
`budget.noAvgHourlyRatePaid`	boolean	Include clients with no avg hourly rate	`false`
`budget.avgHourlyRate.min`	string (USD)	Minimum average rate paid by client	`"40"`
`budget.avgHourlyRate.max`	string (USD)	Maximum average rate paid by client	`"150"`

Duration values: “UP_TO_ONE_MONTH”, “UP_TO_THREE_MONTHS”, “UP_TO_SIX_MONTHS”, “MORE_THAN_SIX_MONTHS”. Workload values: “LESS_THAN_30_HOURS”, “MORE_THAN_30_HOURS”.

Client Requirements

Parameter	Type	Description	Example
`client.paymentMethodVerified`	boolean	Require verified payment method	`true`
`client.phoneNumberVerified`	boolean	Require verified phone number	`true`
`client.minFeedbackScore`	string (0-5)	Minimum client feedback rating	`"4.5"`
`client.totalSpent.min`	string (USD)	Minimum total client spend on Upwork	`"10000"`
`client.totalSpent.max`	string (USD)	Maximum total client spend	`"1000000"`
`client.includeLocations`	object[]	Client locations to include	`[{"type":"COUNTRY","value":"US"}]`
`client.excludeLocations`	object[]	Client locations to exclude	`[{"type":"COUNTRY","value":"IN"}]`
`client.includeIndustry`	string[]	Filter by client industry	`["Technology"]`
`client.excludeIndustry`	string[]	Exclude client industries	`["Healthcare"]`
`client.companySizeRange`	string[]	Filter by company size	`["10-50"]`
`client.timezones`	string[]	IANA timezone identifiers	`["America/New_York"]`
`client.includeWithNoFeedback`	boolean	Include clients with no feedback history	`false`
`client.hireHistory`	string[]	Filter by client hire history	`["1-3"]`
`client.descriptionLanguage.include`	string[]	Include languages (ISO-639-2 codes)	`["eng"]`
`client.descriptionLanguage.exclude`	string[]	Exclude languages (ISO-639-2 codes)	`["ara"]`

Location types: “COUNTRY” (ISO 3166-1 alpha-2) or “REGION” (north_america, europe, asia, south_america, africa, oceania). See Locations reference.

Vendor Preferences

Parameter	Type	Description	Example
`vendor.experienceLevel`	string[]	Required experience level	`["EXPERT"]`
`vendor.englishProficiency`	string	Required English level	`"FLUENT"`
`vendor.type`	string[]	Vendor type filter	`["FREELANCER"]`
`vendor.includeLocations`	object[]	Preferred freelancer locations	`[{"type":"COUNTRY","value":"US"}]`
`vendor.includeFeatured`	boolean	Include only featured jobs	`true`
`vendor.excludeWithQuestions`	boolean	Exclude jobs with screening questions	`true`
`vendor.minCustomJobScore`	string (0-100)	Minimum custom job score	`"50"`
`vendor.includeWithoutCountryPreference`	boolean	Include jobs with no country preference	`true`
`vendor.languages`	string[]	Required languages (ISO-639-1 codes)	`["en", "de"]`

Experience levels: “BEGINNER”, “INTERMEDIATE”, “EXPERT”. English proficiency: “BASIC”, “CONVERSATIONAL”, “FLUENT”, “NATIVE”. Vendor types: “FREELANCER”, “AGENCY”.

Example Response

search_jobs response

{
  "jobs": [
    {
      "uid": "1955020056847176693",
      "title": "React Developer for SaaS Platform",
      "description": "We are looking for an experienced React Developer...",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "skills": ["React", "TypeScript", "Node.js"],
      "externalLink": "https://www.upwork.com/jobs/~021955020056847176693",
      "applicationCost": 6,
      "category": "Web Development",
      "budget": { "fixedBudget": 5000, "hourlyRate": { "min": 40, "max": 80 } },
      "client": {
        "name": "TechStartup Inc",
        "countryCode": "US",
        "paymentMethodVerified": true,
        "stats": { "totalSpent": 125000, "hireRate": 85, "feedbackRate": 4.95 }
      },
      "vendor": { "hireType": "FREELANCER", "experienceLevel": "EXPERT" }
    }
  ],
  "total": 142
}

Try a real example

See search_jobs used end-to-end in a production recipe.

React frontend jobs Senior React/TypeScript in US + EU

get_job

Get full details for a specific Upwork job by its UID. Returns the complete job object including description, skills, budget, client information, screening questions, and vendor requirements.

Parameters

Parameter	Type	Description
`jobId`	string (required)	The UID of the job (e.g., “1955020056847176693”)

Example Response

get_job response

{
  "uid": "1955020056847176693",
  "title": "React Developer for SaaS Platform",
  "description": "We are looking for an experienced React Developer to help build and maintain our SaaS platform...",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "skills": ["React", "TypeScript", "Node.js", "Redux", "REST APIs"],
  "questions": [
    "How many years of React experience do you have?",
    "Can you share a link to a SaaS project you have built?"
  ],
  "budget": { "fixedBudget": null, "hourlyRate": { "min": 40, "max": 80 } },
  "client": {
    "name": "TechStartup Inc",
    "industry": "Technology",
    "companySize": 10,
    "countryCode": "US",
    "stats": { "totalSpent": 125000, "totalHires": 42, "hireRate": 85, "feedbackRate": 4.95 }
  },
  "vendor": {
    "hireType": "FREELANCER",
    "countryCodes": ["US", "CA", "UK"],
    "experienceLevel": "EXPERT",
    "englishLevel": "FLUENT"
  }
}

get_client_activityPremium $5.40/1kRequires Pro or Enterprise

Returns real-time client activity data for a specific job, including how many proposals have been submitted, when the client was last active, how many candidates are being interviewed, invites sent, and unanswered invites.

Parameters

Parameter	Type	Description
`jobId`	string (required)	The UID of the job

Example Response

get_client_activity response

{
  "jobId": "1955020056847176693",
  "proposalCount": 15,
  "lastClientActivity": "2025-01-15T14:30:00.000Z",
  "interviewingCandidates": 3,
  "invitesSent": 5,
  "unansweredInvites": 2
}

get_client_historyPremium $5.40/1kRequires Pro or Enterprise

Returns the client's work history including previous contracts, contractor feedback, ratings, and project outcomes. Useful for evaluating client reliability before applying.

Parameters

Parameter	Type	Description
`jobId`	string (required)	The UID of the job

Example Response

get_client_history response

{
  "jobId": "1955020056847176693",
  "clientHistory": [
    {
      "title": "Full-Stack Developer for MVP",
      "freelancer": "Sarah K.",
      "duration": "3 months",
      "totalPaid": 12500,
      "hourlyRate": 65,
      "rating": 5.0,
      "feedback": "Excellent client, clear requirements."
    }
  ],
  "totalContracts": 42,
  "averageRating": 4.85
}

Output Field Reference

Complete field descriptions for the job objects returned by search_jobs and get_job.

Core Fields

Field	Type	Description
`uid`	string	Unique job identifier
`title`	string	Job posting title
`description`	string	Full job description text
`createdAt`	string (ISO)	When the job was posted
`skills`	string[]	Required skill tags
`externalLink`	string	Direct URL to the Upwork listing
`applicationCost`	integer	Cost in connects to apply
`featured`	boolean	Whether the job is featured
`category`	string	Upwork job category
`ciphertext`	string	Job ciphertext ID (used in URLs)
`customJobScore`	number	Relevance score (0-5)
`questions`	string[]	Screening questions (get_job only)

Budget Object

Field	Type	Description
`budget.fixedBudget`	number \| null	Fixed price in USD
`budget.hourlyRate.min`	number	Min hourly rate in USD
`budget.hourlyRate.max`	number	Max hourly rate in USD

Client Object

Field	Type	Description
`client.name`	string	Client or company name
`client.timezone`	string	IANA timezone identifier
`client.countryCode`	string	ISO country code
`client.paymentMethodVerified`	boolean	Payment verified
`client.industry`	string	Client industry (get_job only)
`client.companySize`	number	Company size (get_job only)
`client.stats.totalSpent`	number	Total spent on Upwork (USD)
`client.stats.totalHires`	number	Total freelancers hired
`client.stats.hireRate`	number	Hire rate percentage
`client.stats.avgRate`	number	Average hourly rate paid
`client.stats.feedbackRate`	number	Average feedback score (0-5)
`client.stats.feedbackCount`	number	Number of feedback reviews

Vendor Object

Field	Type	Description
`vendor.hireType`	string	FREELANCER or AGENCY
`vendor.countryCodes`	string[]	Preferred freelancer countries
`vendor.experienceLevel`	string	BEGINNER, INTERMEDIATE, or EXPERT
`vendor.englishLevel`	string	BASIC, CONVERSATIONAL, FLUENT, or NATIVE