# Craigslist Search API Documentation

Search Craigslist postings on any city site or subarea and in any category, with a keyword, price range and sort order. Each result has the posting id, title, url, price (whole units, with currency when known), images, location with approximate coordinates, the time of the latest bump (ISO 8601 UTC) and for housing the bedrooms and area. Results come in pages of 360; page up to 28 (Craigslist exposes at most 10000 results per search). Contact data is never returned. A valid search with no match is a successful empty result.

- **Documentation:** [https://scrappa.co/docs/craigslist-api/craigslist_search](https://scrappa.co/docs/craigslist-api/craigslist_search)
- **API group:** Craigslist API
- **Endpoint:** `GET https://scrappa.co/api/craigslist/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 |
| --- | --- | --- | --- |
| `site` | string | No | Craigslist city site hostname from the sites endpoint, e.g. portland or sfbay. Required unless subarea is set. Example: portland. |
| `subarea` | string | No | Subarea abbreviation from the sites endpoint, e.g. sfc for the city of San Francisco. Use instead of site. |
| `category` | string | No | Category code from the categories endpoint, e.g. bik (bicycles by owner). Aggregate codes also work: sss (all for sale), bia (all bicycles), hhh (all housing). Defaults to sss. |
| `query` | string | No | Search keywords, up to 200 characters. Example: bike. |
| `min_price` | integer | No | Minimum price in whole units of the site currency. Example: 50. |
| `max_price` | integer | No | Maximum price in whole units of the site currency. Must be at least min_price. Example: 300. |
| `sort` | string | No | date, dateoldest, rel, priceasc or pricedsc. Craigslist defaults to relevance with a query and to newest first without. |
| `page` | integer | No | 1-based page number, 1 to 28. Each page has up to 360 results. Defaults to 1. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/craigslist/search?site=portland&category=bia&query=bike&min_price=50&max_price=300"
```

## Example response

```json
{
    "success": true,
    "data": {
        "total": 831,
        "page": 1,
        "per_page": 360,
        "has_more": true,
        "results": [
            {
                "position": 1,
                "id": "g5tuoYXMyVFFgpXzYbiXMq",
                "posting_id": 7946124093,
                "title": "LeMond Greg Lemond Road Bike 55cm ((( REDUCED )))",
                "url": "https://www.craigslist.org/view/g5tuoYXMyVFFgpXzYbiXMq",
                "price": 200,
                "currency": "USD",
                "images": [
                    "https://images.craigslist.org/00f0f_52oL7PFWTmc_0CI0lN_600x450.jpg",
                    "https://images.craigslist.org/00o0o_7s8PevWIQe8_0CI0lN_600x450.jpg",
                    "https://images.craigslist.org/00505_jFRAv7Cqove_0lN0CI_600x450.jpg"
                ],
                "slug": "portland-lemond-greg-lemond-road-bike",
                "location": {
                    "name": "Tigard",
                    "site": "portland",
                    "subarea": "wsc",
                    "latitude": 45.4403,
                    "longitude": -122.7793
                },
                "bumped_at": "2026-10-15T19:24:12Z"
            },
            {
                "position": 2,
                "id": "6amiQ1na2PT7HVYjM9TDvR",
                "posting_id": 7931050968,
                "title": "Centurion Le Mans RS Road Bike ( NICE )",
                "url": "https://www.craigslist.org/view/6amiQ1na2PT7HVYjM9TDvR",
                "price": 200,
                "currency": "USD",
                "images": [
                    "https://images.craigslist.org/00303_4rWBDSH5ngs_0CI0lN_600x450.jpg",
                    "https://images.craigslist.org/00v0v_6LPhiNeAJpb_0lN0CI_600x450.jpg",
                    "https://images.craigslist.org/00G0G_5tPzrY1qGiI_0lN0CI_600x450.jpg"
                ],
                "slug": "portland-centurion-le-mans-rs-road-bike",
                "location": {
                    "name": "Tigard",
                    "site": "portland",
                    "subarea": "wsc",
                    "latitude": 45.4403,
                    "longitude": -122.7793
                },
                "bumped_at": "2026-10-15T19:23:50Z"
            }
        ]
    },
    "meta": {
        "endpoint_family": "search",
        "billable": true
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A parameter is missing or invalid. This response is not billable. |
| 422 | Unsupported Site or Category | Craigslist does not support this site, subarea or category combination. This response is not billable. |
| 502 | Invalid Source Response | Craigslist answered with a shape that no longer matches the documented contract. This response is not billable. |
| 503 | Service Unavailable | The upstream service is temporarily unavailable. Please retry shortly. |

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