# Upwork Job Search API Documentation

Scrappa's `GET /api/upwork/jobs` returns public job posts from Upwork's visitor feed.

## Input

`query` is sent to Upwork's public search. Upwork ranks by relevance, so rows are not matched again locally. `category`, `budget` (minimum USD), `job_type` and `experience` are applied to the returned page as a safety net, so they filter the rows you get, not the upstream window. `job_type` accepts `hourly` or `fixed`; both are derived from the same published budget field, so `job_type` and `budget.type` always agree. Other type values are rejected. `experience` accepts `entry` only. Other tiers were below the 80% production soak and return 422, so they never yield a flaky empty list. No row violates a requested filter. Page N never carries page 1 data. A zero-result query returns a successful empty list. When a filter is active, `pagination.total` is null because the upstream total counts other rows.

## What you get

`data.jobs[]` has `id` (the Upwork ciphertext), `title`, `description`, `url`, `job_type`, `budget` (`min`, `max`, `amount`, `currency`, `type`), `skills`, `client`, `posted_at` (ISO 8601) and `proposals`. Skills come from the public page. `proposals` is `null` when Upwork omits the proposal tier on search. `data.pagination` has `page`, `per_page`, `has_more` and `total`. `per_page` is the real upstream window, including when Upwork returns fewer than 50 rows. Prices are numbers with currency. Fields that Upwork does not publish stay `null`.

## Credits

A successful request costs **1 credit**. Errors and blocks cost nothing. The response shows the charge in `meta.credits_charged`.

- **Documentation:** [https://scrappa.co/docs/upwork-api/upwork_jobs](https://scrappa.co/docs/upwork-api/upwork_jobs)
- **API group:** Upwork API
- **Endpoint:** `GET https://scrappa.co/api/upwork/jobs`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | No | Keywords sent to Upwork public search and ranked by relevance. |
| `category` | string | No | Matches title, description and skills on the returned page. |
| `budget` | number | No | Minimum budget in USD. |
| `job_type` | string | No | hourly or fixed. |
| `experience` | string | No | entry only. |
| `page` | integer | No | Page number, starting at 1. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/upwork/jobs?query=logo+design&page=1"
```

## Example response

```json
{
    "success": true,
    "data": {
        "jobs": [
            {
                "id": "~022121837851516269848",
                "title": "Logo design for a new brand",
                "description": "We need a modern logo and brand guide.",
                "url": "https://www.upwork.com/jobs/logo-design-for-a-new-brand_022121837851516269848/",
                "job_type": "fixed",
                "budget": {
                    "min": null,
                    "max": null,
                    "amount": 500,
                    "currency": "USD",
                    "type": "fixed"
                },
                "skills": [
                    "Logo Design",
                    "Graphic Design"
                ],
                "client": {
                    "country": null,
                    "spent": null,
                    "tier": "Entry Level"
                },
                "posted_at": "2026-11-16T10:00:00Z",
                "proposals": null
            }
        ],
        "pagination": {
            "page": 1,
            "per_page": 50,
            "has_more": true,
            "total": 1200
        }
    },
    "meta": {
        "endpoint_family": "upwork.jobs.search",
        "billable": true,
        "credits_charged": 1
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A parameter is missing, unknown or unusable. Unknown parameters are rejected, never ignored. Non-billable. |
| 503 | Upstream Unavailable | Upwork blocked the request or could not be reached. Non-billable. Clients are never rate limited. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)
