# Upwork Jobs

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/upwork/jobs` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 2 credits per call |
| **Documentation** | https://www.piloterr.com/library/upwork-jobs |

## Description

Upwork Jobs API: search freelance job listings by skill slug or URL. Returns budgets, skills, experience level and pagination via browser rendering.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/upwork/jobs' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### API development jobs (page 1)

```json
{
  "skill": "api-development",
  "title": "Find the Best API Developer Jobs",
  "results": [
    {
      "title": "Full-stack Shopify + Make.com + Gemini AI Automation Setup",
      "job_id": "022071658395247542131",
      "skills": [
        "HTML",
        "HTML5",
        "CSS",
        "Shopify"
      ],
      "currency": "USD",
      "duration": "1 to 3 months",
      "job_type": "fixed",
      "posted_at": "2026-06-29T18:13:45+0000",
      "budget_max": null,
      "budget_min": 800,
      "posted_ago": "14 hours ago",
      "description": "Dear Expert,\nBelow you can find a description of my project where your expertise would be needed.\nProject Overview: I am looking for a full-stack automation expert/agency to build a completely turnkey...",
      "listing_url": "https://www.upwork.com/freelance-jobs/apply/Full-stack-Shopify-Make-com-Gemini-Automation-Setup_~022071658395247542131/",
      "hours_per_week": null,
      "experience_level": "Expert"
    },
    {
      "title": "Looking for an AI Agent Developer for Social Media Automation",
      "job_id": "022071659921584263119",
      "skills": [
        "Lead Generation",
        "Artificial Intelligence",
        "Python"
      ],
      "currency": "USD",
      "duration": "1 to 3 months",
      "job_type": "fixed",
      "posted_at": "2026-06-29T18:19:49+0000",
      "budget_max": null,
      "budget_min": 13000,
      "posted_ago": "13 hours ago",
      "description": "I am looking to build an AI agent that can manage and handle social media profiles across platforms like Facebook, Instagram, LinkedIn, and TikTok.\nThe goal is to create an AI-powered system that can ...",
      "listing_url": "https://www.upwork.com/freelance-jobs/apply/Looking-for-Agent-Developer-for-Social-Media-Automation_~022071659921584263119/",
      "hours_per_week": null,
      "experience_level": "Expert"
    }
  ],
  "pagination": {
    "next": null,
    "page": 1,
    "per_page": 30,
    "total_pages": 206,
    "total_results": 6156
  }
}
```

## Documentation

## Overview
The **Upwork Jobs API** returns freelance job listings from [Upwork](https://www.upwork.com) skill pages (`/freelance-jobs/{skill}/`). Pass a **skill slug** or **full URL** and receive structured JSON with job titles, budgets, skills, experience level, and pagination.

Upwork pages require **browser rendering** (`wait_for=#__nuxt`, ~8s) to load the Nuxt payload and job tiles.

## Quickstart
```
GET https://api.piloterr.com/v2/upwork/jobs?query=api-development
```

Via POST:
```
POST https://api.piloterr.com/v2/upwork/jobs
Content-Type: application/json

{"query": "api-development", "return_page_source": false}
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Skill slug or `/freelance-jobs/{skill}/` URL |
| `return_page_source` | boolean | no | Raw HTML as `{"result": "..."}` (default: `false`) |

## Response: each job (`results[]`)
| Field | Type | Description |
|---|---|---|
| `job_id` | string | Upwork job ID |
| `title` | string | Job title |
| `description` | string | Job description |
| `listing_url` | string | Apply URL |
| `job_type` | string | `fixed` or `hourly` |
| `budget_min` | number \| null | Minimum budget |
| `budget_max` | number \| null | Maximum budget |
| `currency` | string | ISO 4217 code (`USD`) |
| `duration` | string \| null | Estimated duration |
| `hours_per_week` | string \| null | Weekly hours |
| `experience_level` | string | Entry / Intermediate / Expert |
| `skills` | string[] | Required skills |
| `posted_at` | string | ISO-like timestamp |
| `posted_ago` | string | Relative time label |

## Response: pagination
| Field | Type | Description |
|---|---|---|
| `page` | integer | Current page |
| `per_page` | integer | Jobs on this page |
| `total_results` | integer \| null | Total matching jobs |
| `total_pages` | integer \| null | Total pages |
| `next` | string \| null | Next page URL |

## Upwork API workflow
1. **Upwork Jobs**: discover open roles by skill (this endpoint)
2. **Upwork Freelancer**: enrich talent profiles from a freelancer URL
3. **Upwork Services**: browse Project Catalog listings by category
4. **Upwork Services Info**: fetch full catalog product details from a product URL

## Error codes
| Code | Meaning |
|---|---|
| `400` | Missing or invalid `query` |
| `404` | Page not parseable |
| `500` | Rendering or parsing error |

## Notes
- Costs **2 credits** per call (browser rendering).

## Main use cases
- **Job market monitoring**: track new Upwork postings by skill
- **Lead generation**: discover projects matching your stack
- **Competitive intelligence**: analyze budgets and experience levels by category