# Troubleshooting And FAQ

> Answer common API access, authentication, pagination, filtering, response, and error-handling questions.

> Resolve common API access, authentication, `aid`, pagination, filtering, response, and retry questions.

Use this page when an API request fails or returned data does not match expectations.

---

## Access And Keys

| Question | Answer |
| --- | --- |
| How do I get API access? | API Access must be enabled for the relevant team or package. Contact Kommon Poll if it is not available. |
| Where do I create an API key? | Open Kommon Poll, go to **Integrations**, then open **API Access**. |
| Why can I not see API Access for my team? | The feature may not be enabled for that team or package, or you may not have the required permissions. |
| Can one key access multiple teams? | A key should be created for the team the integration needs. Use `GET /v4/list` to confirm what the key can access. |
| Can I retrieve the full API key again later? | No. Copy and store the full key when it is created. If it is lost, create a replacement key and revoke the old one. |
| How do I revoke or rotate a key? | Create a replacement key, update the integration, confirm the new key works, then revoke the old key. |

---

## aid And Saved Searches

| Question | Answer |
| --- | --- |
| What is an `aid`? | `aid` is the saved-search identifier returned by `GET /v4/list`. |
| How do I find the correct `aid`? | Call `GET /v4/list`, choose the saved search, and copy its `aid`. |
| Why is `aid` required by `GET /v4/search`? | Search requests run against one authorized saved search. The `aid` identifies which one to use. |
| What does `GET /v4/list` return? | It returns saved searches, team saved searches, and recent history available to the authenticated key. |

---

## Search Requests

| Question | Answer |
| --- | --- |
| What is the default search period? | If `duration` is omitted, the default period is `30d`. |
| How do I request individual mentions instead of overview analytics? | Send a positive `dataSize`, such as `dataFrom=0&dataSize=50`. |
| How do I paginate results? | Increase `dataFrom` by the page size on each request. |
| What is the maximum `dataSize`? | `dataSize` is capped at `500` per request. |
| How do I filter by platform, sentiment, author, domain, or date? | Use the relevant filters in the [Search Parameter Reference](/api-endpoint-search#search-parameter-reference). |
| What is the difference between publication, collection, and ingestion time? | Publication time is when source content was published. Collection or ingestion time is when Kommon Poll received or processed it. |

---

## Responses And Metrics

| Question | Answer |
| --- | --- |
| What do reach, interactions, influence, and sentiment mean? | Use the definitions in the [Response Guide](/api-endpoint-search#response-guide), and avoid treating platform-specific metrics as identical across every source. |
| Why are some fields missing or null? | Not every platform provides every metric, and missing values should not automatically be interpreted as zero. |
| Can the API create or edit saved searches? | No. The API is read-only. Create and manage saved searches in Kommon Poll. |
| Does the API support `POST`, `PUT`, or `DELETE`? | No. Use `GET` for supported API requests. |
| What is the difference between the API and MCP? | The API is for deterministic application requests. MCP is for AI assistant workflows that use Kommon Poll as a tool. |

---

## Errors

| Question | Answer |
| --- | --- |
| What should I do after `400`? | Correct the request. Common causes include missing `aid`, invalid date format, invalid `timerange`, unsupported `sortBy`, or an invalid range. |
| What should I do after `401`? | Check the bearer token and confirm the full API key was copied correctly. |
| What should I do after `403`? | Confirm the key has access to the team, package, resource, or feature. |
| What should I do after `404`? | Use `GET /v4/list` and verify that the `aid` is available to the key. |
| What should I do after `429`? | Retry with bounded exponential backoff and respect configured usage limits. |
| What should I do after `5xx`? | Retry transient failures with bounded exponential backoff and a maximum retry count. |

---

## Scheduled Reports

For scheduled reports:

- Store the API key in a server-side secret.
- Store the selected `aid` in configuration.
- Use an explicit `duration` and `timezone`.
- Paginate mention records when needed.
- Record the reporting period and filters in the output.
- Redact API keys and bearer headers from logs.