# Totaljobs Job Search API Documentation

<p><strong>Totaljobs Job Search</strong> returns 25 public UK job listings per page from the same result list the site renders. Each job carries its numeric id, title, company id and name, full size logo url, location, post code, GBP salary text and number, posting dates in ISO 8601, labels, skills, snippet and job url. Pagination exposes page, per page, page count and total count. Facets and selected filters come from the same query.</p><p>Filters are passed to the site and checked again before an answer is sent. A page past the end returns 422; page one is never relabelled. The newer engine has no posting date filter, so posted_within is refused there. A request costs 1 credit. A failed request is not charged.</p>

- **Documentation:** [https://scrappa.co/docs/totaljobs-api/totaljobs_search](https://scrappa.co/docs/totaljobs-api/totaljobs_search)
- **API group:** Totaljobs API
- **Endpoint:** `GET https://scrappa.co/api/totaljobs/jobs/search`

## 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 | Yes | Job title or keywords, for example python. |
| `location` | string | No | Place, for example London. |
| `radius` | integer | No | Miles around the location, 1 to 100. UK engine only. |
| `salary_min` | integer | No | Minimum annual salary in GBP. |
| `job_type` | string | No | permanent, contract, temporary, part_time or work_from_home. |
| `posted_within` | integer | No | 1, 3, 7 or 14 days. UK engine only. |
| `work_from_home` | boolean | No | true or false. |
| `engine` | string | No | uk (default) or stepstone. |
| `page` | integer | No | Page number, default 1. |

## Example response

```json
{
    "data": {
        "jobs": [
            {
                "id": "108334869",
                "url": "/job/machine-learning-engineer/client-server-job108334869",
                "title": "Machine Learning Engineer",
                "salary": {
                    "max": 100000,
                    "min": 85000,
                    "raw": "\u00a385000 - \u00a3100000 per annum",
                    "unit": "year",
                    "currency": "GBP"
                },
                "date_posted": "2026-11-17T14:38:29Z"
            }
        ],
        "pagination": {
            "page": 1,
            "total": 2403,
            "per_page": 25,
            "has_next_page": true
        }
    },
    "success": true
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Invalid Page | The requested page is past the end of the result list. |
| 422 | Invalid Filter | The filter is not available on the selected engine. |
| 503 | Upstream Unavailable | The source could not be reached. The request is not charged. |

## 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)
