# Kyero Agency Directory API Documentation

Scrappa's `GET /api/kyero/agents` lists the estate agencies of one Kyero location, 20 per page.

## What you get

Each agency has `id`, `name`, `slug`, `logo_url`, a short `about` text, `languages`, `for_sale_count`, `long_term_rent_count`, `prime` and the `path` that the agent endpoint takes. `pagination` has `page`, `pages` and `count`.

## Country

Send `country` together with the location. It must be the country of the location. Take it from `agents_country` in the autocomplete response. A mismatch fails without a charge.

## Contact details

Agency phone numbers and WhatsApp numbers are hidden on Kyero and are not returned.

## Pagination

`page` runs from 1 to 50. The response never returns one page's data under another page number.

- **Documentation:** [https://scrappa.co/docs/kyero-api/kyero_agents](https://scrappa.co/docs/kyero-api/kyero_agents)
- **API group:** Kyero API
- **Endpoint:** `GET https://scrappa.co/api/kyero/agents`

## 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 |
| --- | --- | --- | --- |
| `country` | string | Yes | es, pt, it or fr. Must match the location. |
| `location_id` | integer | Yes | Location id from the autocomplete endpoint. |
| `location_slug` | string | Yes | Location slug from the autocomplete endpoint. |
| `page` | integer | No | Result page, 1 to 50. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/kyero/agents?country=es&location_id=31673&location_slug=marbella"
```

## Example response

```json
{
    "success": true,
    "country": "es",
    "location": {
        "id": 31673,
        "slug": "marbella",
        "name": "Marbella"
    },
    "agents": [
        {
            "id": 24939,
            "name": "Holdsworth Estates",
            "logo_url": "https://img.kyero.com/fit/125x125/agents/logos/24/24939.jpg",
            "type": null,
            "prime": true,
            "path": "/en/spain/estate-agents/profile/holdsworth-estates-a24939",
            "url": "https://www.kyero.com/en/spain/estate-agents/profile/holdsworth-estates-a24939",
            "slug": "holdsworth-estates",
            "status": "live",
            "about": "We are partners on the journey to the perfect property on the Costa del Sol.",
            "languages": [
                "en",
                "es"
            ],
            "for_sale_count": 28,
            "long_term_rent_count": null
        }
    ],
    "pagination": {
        "page": 1,
        "pages": 5,
        "count": 97,
        "max_pages": 50,
        "has_next": true
    },
    "title": "Estate agents in Marbella",
    "meta": {
        "billable": true,
        "attempts": 1,
        "last_status": 200,
        "endpoint_family": "agents"
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A query parameter failed validation, or a path, id or slug is unusable (`invalid_parameter`). Non-billable. |
| 503 | Upstream Unavailable | Kyero could not be reached after retries, answered a different page than requested, did not apply the filters, or answered with a body this API cannot read (`upstream_unavailable`, `upstream_blocked`, `pagination_mismatch`, `filter_not_honoured`, `parser_drift`). Retryable and never billed. 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)