# API Overview

> Understand the Kommon Poll API, base URL, read-only GET workflow, API vs MCP, and common integration patterns.

> Build read-only Kommon Poll integrations using the V4 API.

The Kommon Poll API gives approved integrations programmatic read access to authorized Kommon Poll search data.

Base URL:

```text
https://api.kommonpoll.com/v4
```

Current API endpoints:

| Endpoint | Purpose |
| --- | --- |
| `GET /v4/list` | Discover saved searches, team saved searches, and recent search history available to your API key. |
| `GET /v4/search` | Retrieve overview analytics and, when requested, paginated mention records for an authorized saved search. |

The API is read-only. It does not create, edit, or delete saved searches.

---

## What You Can Build

Common API use cases include:

- Reporting systems.
- BI dashboards.
- Scheduled analysis jobs.
- Data pipelines.
- Business applications.
- Research workflows.
- Custom analytics interfaces.

---

## API vs MCP vs Kommon Poll

| Use | Best option | Why |
| --- | --- | --- |
| Build a deterministic backend integration | API | Your application controls every request and response. |
| Create a scheduled reporting pipeline | API | Server-side automation can run on a repeatable schedule. |
| Ask an AI assistant to analyze Kommon Poll conversationally | [MCP](/mcp) | The assistant can use Kommon Poll as an AI tool. |
| Explore dashboards and configure saved searches | Kommon Poll application | The product interface is built for interactive setup and administration. |
| Feed Kommon Poll into Power BI or a warehouse | API | Structured requests support repeatable data retrieval. |

---

## Basic Workflow

1. Create or identify a saved search in Kommon Poll.
2. Generate an API key for the team that owns the saved search.
3. Call `GET /v4/list` to discover searches available to the key.
4. Copy the saved search `aid` from the list response.
5. Call `GET /v4/search?aid=<AID>`.
6. Add filters, date controls, sorting, or pagination parameters as required.
7. Use the returned aggregates and mention records in your reporting or application workflow.

---

## Choose A Page

| Goal | Start here |
| --- | --- |
| Enable API access and create a key | [Getting API Access And Keys](/api-getting-access) |
| Authenticate the first request | [Authentication](/api-authentication) |
| Discover saved searches and `aid` values | [GET /v4/list](/api-endpoint-list) |
| Retrieve analytics or mentions | [GET /v4/search](/api-endpoint-search) |
| Look up request parameters | [Search Parameter Reference](/api-endpoint-search#search-parameter-reference) |
| Interpret metrics and mention records | [Response Guide](/api-endpoint-search#response-guide) |
| Handle validation, limits, and retries | [Errors, Limits, And Retries](/api-endpoint-search#errors-limits-and-retries) |
| Copy starter requests | [Code Examples](/api-code-examples) |
| Apply the API to business workflows | [API Cookbooks](/api-cookbooks) |
| Secure production integrations | [Security And Best Practices](/api-security-best-practices) |
| Resolve common questions | [Troubleshooting And FAQ](/api-troubleshooting-faq) |

---

## Recommended Starting Stack

For most integrations, start with:

- One API key per application and environment.
- One stored `aid` per saved search used by the integration.
- `GET /v4/list` during setup or configuration.
- `GET /v4/search` for recurring analytics and mention retrieval.
- `duration`, `timezone`, `dataFrom`, `dataSize`, and `sortBy` set explicitly in production jobs.
- Bounded retries for `429` and temporary `5xx` responses.
- Redaction for the `Authorization` header in logs.
- Clear reporting notes that state the `aid`, period, timezone, and filters used.