Rate Limits
Upwork Job Search MCP enforces rate limits to ensure fair usage and service stability. Limits are based on your subscription plan.
Limits by Plan
| Plan | Monthly Jobs | Per Minute | API Keys |
|---|---|---|---|
| Free$0/mo | ~850 | 10 | 1 |
| Pro$29/mo | ~5,000 | 60 | 3 |
| EnterpriseCustom | Unlimited | 600 (raise on request) | Unlimited |
Rate Limit Headers
Every response includes headers that indicate your current rate limit status:
X-RateLimit-LimitMaximum number of jobs allowed per month.
X-RateLimit-RemainingNumber of jobs remaining in the current period.
X-RateLimit-ResetUTC timestamp (seconds) when the monthly counter resets.
Retry-AfterSeconds to wait before retrying (only present on 429 responses).
Exceeding Limits
When you exceed your rate limit, the server returns a 429 Too Many Requests status code. The response includes a Retry-After header indicating how long to wait.
Unused jobs do not roll over
Monthly job quotas reset on the first day of each billing cycle. Unused jobs from the previous period are not carried forward.
Premium addons consume credit at their own rate
Calls to get_client_activity and get_client_history consume your Pro credit pool at $5.40/1k each. Once the pool is exhausted — and any prepaid credit packs are spent — the next request is rejected with a 402 Payment Required; there is no overage. See the Billing page for details.
Best Practices
- Monitor your usage in the dashboard to avoid unexpected limit hits.
- Use specific filters (keywords, budget, client location) to narrow results and reduce search volume.
- Cache job results on the client side — jobs are refreshed every 5-15 minutes.
- Use the limit parameter to control how many results you need per search.
- Implement exponential backoff when receiving 429 responses.
Need higher limits? Contact sales for a custom Enterprise plan.