# GET /v4/list

> Discover saved searches, team saved searches, and recent search history available to an API key.

> Use `GET /v4/list` to discover saved searches and the `aid` values required by `GET /v4/search`.

`GET /v4/list` returns the search resources available to the authenticated API key.

Use this endpoint before `GET /v4/search` when an application needs to resolve a human-readable saved search to an `aid`.

It can also populate project or search selectors in external applications.

---

## 1. Request

| Property | Value |
| --- | --- |
| Method | `GET` |
| URL | `https://api.kommonpoll.com/v4/list` |
| Authentication | Required |
| Query parameters | None required |
| Request body | None |

Example:

```bash
curl https://api.kommonpoll.com/v4/list \
  -H "Authorization: Bearer YOUR_KOMMON_POLL_API_KEY"
```

---

## 2. Response Contents

The response can include:

- Saved searches available to the user.
- Saved searches available through the key's team.
- Recent search history.

Each saved search entry should include an `aid`. This value is the identifier required by `GET /v4/search`.

Applications should store the `aid` as the stable reference for search calls.

---

## 3. Sample Response

```json
{
  "savedSearches": [
    {
      "aid": "brand-abc123",
      "title": "Acme Always-on Monitoring",
      "type": "My Brand",
      "updatedAt": "2026-08-31T10:12:00Z"
    }
  ],
  "teamSavedSearches": [
    {
      "aid": "campaign-def456",
      "title": "Launch Campaign",
      "type": "Campaign",
      "team": "Marketing",
      "updatedAt": "2026-08-30T08:45:00Z"
    }
  ],
  "recentHistory": [
    {
      "aid": "recent-ghi789",
      "title": "Weekend brand spike",
      "searchedAt": "2026-08-29T13:20:00Z"
    }
  ]
}
```

The exact fields returned can depend on the saved search and account context. The important integration field is `aid`.

---

## 4. Common Use Cases

- Populate a project selector in a reporting dashboard.
- Allow a user to choose which Kommon Poll saved search to analyze.
- Resolve a saved-search title to an `aid` during integration setup.
- Verify which searches are available to a specific API key.
- Discover the correct `aid` before a scheduled reporting job is configured.

---

## 5. Implementation Notes

- Cache the list response where appropriate.
- Refresh the list when a user changes team, creates a new saved search, or updates integration settings.
- Do not assume saved-search titles are unique.
- Use `aid`, not title, as the durable reference for search calls.
- Handle empty lists by checking the API key's team and API Access status.