# Search Events

`POST`

### Overview

Search and browse available prediction markets.

### Authentication

No authentication required.

### Request

* Method: `POST`
* Path: `/api/events/search`

#### Query Parameters

| Parameter | Type    | Required | Default | Description     |
| --------- | ------- | -------- | ------- | --------------- |
| page      | integer | No       | 0       | Zero-based page |
| size      | integer | No       | 20      | Items per page  |

#### Request body

| Field | Type      | Required | Description                                                                                      |
| ----- | --------- | -------- | ------------------------------------------------------------------------------------------------ |
| sb    | string    | No       | Sort by — `VOLUME_24H`, `TOTAL_VOLUME`, `LIQUIDITY`, `NEWEST`, `OLDEST`, `ENDING_SOON`, `CHANCE` |
| sd    | string    | No       | Sort direction — `ASC` or `DESC`                                                                 |
| l     | string    | No       | Language — `en`, `de`, `es`, `pt`, `zh`, `ja`, `ko`, `id`                                        |
| ss    | string    | No       | Search string                                                                                    |
| c     | string\[] | No       | Category slugs to filter                                                                         |
| t     | string\[] | No       | Tag names to filter                                                                              |
| ft    | boolean   | No       | Featured events only                                                                             |

#### Example request

```json
{
  "sb": "VOLUME_24H",
  "sd": "DESC",
  "l": "en",
  "ss": "bitcoin"
}
```

### Response `200 OK`

```json
{
  "content": [
    {
      "id": "54ccea1a-16fd-469c-8018-84b375243e8a",
      "title": "Will BTC reach $100k by end of 2026?",
      "outcomes": [
        {
          "marketId": "b21f6fd8-b9d1-4b9f-bb79-ef141e3dcb76",
          "yesId": "e7c4fed5-e7f4-4ec4-9b55-0bb41b83d813",
          "noId": "c7b372ab-de41-4cea-b51a-12807ac63029"
        }
      ]
    }
  ],
  "totalElements": 500,
  "totalPages": 25
}
```

| Field               | Type    | Description                  |
| ------------------- | ------- | ---------------------------- |
| content             | array   | Array of events              |
| content\[].id       | string  | Event ID                     |
| content\[].title    | string  | Event title                  |
| content\[].outcomes | array   | List of outcomes and markets |
| totalElements       | integer | Total number of events       |
| totalPages          | integer | Total number of pages        |

### Error variants

Common public endpoint errors:

| Code | Description                         |
| ---- | ----------------------------------- |
| 400  | Bad Request — Invalid parameters    |
| 404  | Not Found — Resource does not exist |
| 500  | Internal Server Error               |

**Error response**

```json
{
  "status": 400,
  "error": "Bad Request",
  "message": "Invalid parameters"
}
```

### Python example

{% code title="search\_events.py" %}

```python
import requests

response = requests.post(
    "https://event-service.outpoll.com/api/events/search",
    params={"page": 0, "size": 20},
    json={
        "sb": "VOLUME_24H",
        "sd": "DESC",
        "l": "en",
        "ss": "bitcoin",
    },
    timeout=10,
)
response.raise_for_status()

data = response.json()

for event in data["content"]:
    print(f"{event['id']} | {event['title']}")
```

{% endcode %}