API

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.

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.

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.
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.

Question	Answer
What do reach, interactions, influence, and sentiment mean?	Use the definitions in the 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.

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.

For scheduled reports: