# GET /v4/search

> Use saved-search identifiers, date controls, pagination, sorting, and filters to retrieve analytics and mentions.

> Use `GET /v4/search` to retrieve Kommon Poll overview analytics, paginated mention records, filtered result sets, response data, and request validation details.

`GET /v4/search` is the main Kommon Poll search and analytics endpoint.

Every request is based on one authorized saved search identified by `aid`.

An `aid`-only request returns the default overview for that saved search. Additional parameters can narrow the date window, retrieve mention pages, change sorting, apply filters, or control collection and ingestion date windows.

---

## 1. Minimal Request

```text
GET https://api.kommonpoll.com/v4/search?aid=<AID>
```

Rules:

- `aid` is required.
- Use `GET` only.
- Do not send a request body.
- If no `duration` is supplied, the default reporting period is `30d`.
- If no `timezone` is supplied, UTC is used for date and time interpretation.

---

## 2. Overview vs Mentions

| Goal | Request pattern | Expected output |
| --- | --- | --- |
| Overview analytics | `aid=<AID>` | Aggregate analytics for the saved search and selected filters. |
| Individual mentions | `aid=<AID>&dataFrom=0&dataSize=50` | A page of mention records. |
| Filtered mentions | Add filters and `sortBy` to a mentions request | Mention records matching the selected filter set. |
| Next page | Increase `dataFrom` by the page size | The next result page. |

---

## 3. Request Examples

| Use case | Request |
| --- | --- |
| Default 30-day overview | `GET /v4/search?aid=<AID>` |
| 7-day overview | `GET /v4/search?aid=<AID>&duration=7d` |
| 7-day overview in Sri Lanka time | `GET /v4/search?aid=<AID>&duration=7d&timezone=Asia%2FColombo` |
| First 50 newest mentions | `GET /v4/search?aid=<AID>&duration=30d&dataFrom=0&dataSize=50&sortBy=dateDesc` |
| Next 50 mentions | `GET /v4/search?aid=<AID>&duration=30d&dataFrom=50&dataSize=50&sortBy=dateDesc` |
| Negative mentions | `GET /v4/search?aid=<AID>&duration=7d&dataFrom=0&dataSize=50&maxSent=-0.01&sortBy=dateDesc` |
| Most influential negative mentions | `GET /v4/search?aid=<AID>&duration=7d&dataFrom=0&dataSize=50&maxSent=-0.01&sortBy=infDesc` |
| Facebook and Instagram only | `GET /v4/search?aid=<AID>&platforms=facebook,instagram` |
| English and Sinhala | `GET /v4/search?aid=<AID>&filterLanguage=en,si` |
| Specific reporting dates | `GET /v4/search?aid=<AID>&duration=010826-310826` |
| Business-author mentions only | `GET /v4/search?aid=<AID>&filterBusiness=true` |
| Selected domains only | `GET /v4/search?aid=<AID>&filterIncludeDomain=example.com,example.org` |
| High-priority complaints | `GET /v4/search?aid=<AID>&filterPriority=high&actionType=complaint&dataFrom=0&dataSize=50&sortBy=dateDesc` |

---

## 4. Search Parameter Reference

All search requests require an `aid` from `GET /v4/list`.

When a parameter is not needed, omit it rather than sending an empty value.

### Core Parameters

| Parameter | Required | Type | Default | Meaning | Example |
| --- | --- | --- | --- | --- | --- |
| `aid` | Yes | String | None | Saved-search identifier returned by `GET /v4/list`. | `aid=abc123` |
| `duration` | No | String | `30d` | Published-date reporting period. | `duration=7d` |
| `timerange` | No | String | Full day | Optional time-of-day window. | `timerange=0900-1800` |
| `timezone` | No | String | `UTC` | Timezone used for date and time interpretation. | `timezone=Asia%2FColombo` |
| `dataFrom` | No | Integer | `0` | Result offset when retrieving mentions. | `dataFrom=0` |
| `dataSize` | No | Integer | `0` | Number of mention records to return. Maximum `500`. | `dataSize=50` |
| `sortBy` | No | Enum | Default ordering | Controls mention ordering. | `sortBy=dateDesc` |

### duration

Rolling duration format:

```text
Nd
```

Examples:

- `duration=1d`
- `duration=7d`
- `duration=30d`
- `duration=90d`
- `duration=365d`

Rules:

- Rolling duration must be greater than zero.
- Maximum supported rolling duration is `3660d`.
- Explicit date-range format is `DDMMYY-DDMMYY`.
- Example explicit range: `duration=010826-310826`.
- The start date cannot be after the end date.

### timerange

Format:

```text
HHMM-HHMM
```

Example:

```text
timerange=0900-1800
```

Rules:

- Hours must be `00` to `23`.
- Minutes must be `00` to `59`.
- Use `timezone` when the reporting day should be interpreted in a specific local timezone.

### timezone

Use an IANA timezone name.

Examples:

- `Asia/Colombo`
- `Europe/London`
- `America/New_York`
- `Australia/Sydney`

`UTC` and `Z` are accepted as UTC references.

The timezone affects rolling-date boundaries and the interpretation of `timerange`.

### Pagination

Use `dataFrom` as the zero-based result offset and `dataSize` as the requested page size.

```text
GET /v4/search?aid=<AID>&dataFrom=0&dataSize=50
GET /v4/search?aid=<AID>&dataFrom=50&dataSize=50
GET /v4/search?aid=<AID>&dataFrom=100&dataSize=50
```

Rules:

- `dataFrom` must be an integer greater than or equal to `0`.
- `dataSize` must be between `0` and `500`.
- To return mentions, request a positive `dataSize`.
- For large exports, paginate instead of attempting to retrieve the full dataset in one request.

### Sorting

| Value | Meaning |
| --- | --- |
| `default` | Kommon Poll default result ordering. |
| `relevance` | Highest search relevance first. |
| `dateAsc` | Oldest published mentions first. |
| `dateDesc` | Newest published mentions first. |
| `dateAscCol` | Earliest collected mentions first. |
| `dateDescCol` | Latest collected mentions first. |
| `engagementsAsc` | Lowest engagement first. |
| `engagementsDesc` | Highest engagement first. |
| `polAsc` | Most negative sentiment first. |
| `polDesc` | Most positive sentiment first. |
| `infAsc` | Lowest influence first. |
| `influenceAsc` | Lowest influence first. |
| `infDesc` | Highest influence first. |
| `influenceDesc` | Highest influence first. |
| `intAsc` | Lowest interactions first. |
| `intDesc` | Highest interactions first. |
| `reachAsc` | Lowest reach or views first. |
| `reachDesc` | Highest reach or views first. |

### Source, Location, And Audience Filters

| Parameter | Type | Meaning | Example |
| --- | --- | --- | --- |
| `platforms` | List | Limit results to one or more supported platforms or sources. | `platforms=facebook,instagram` |
| `filterCountry` | List | Filter by country. | `filterCountry=LK,IN` |
| `filterNationality` | List | Filter by author nationality where available. | `filterNationality=Sri%20Lankan` |
| `filterAge` | List | Filter by available age-band classifications. | `filterAge=25-34` |
| `filterEducation` | List | Filter by education classification where available. | `filterEducation=University` |
| `filterIncome` | List | Filter by income classification where available. | `filterIncome=High` |
| `filterGender` | List | Filter by gender classification where available. | `filterGender=female` |
| `filterLanguage` | List | Filter by detected or content language. | `filterLanguage=en,si` |
| `filterBusiness` | Boolean | Include only business or non-business authors where available. | `filterBusiness=true` |

### Author, Hashtag, And Domain Filters

| Parameter | Type | Meaning | Example |
| --- | --- | --- | --- |
| `filterIncludeAuthor` | List | Only return mentions from selected authors or usernames. | `filterIncludeAuthor=brandaccount` |
| `filterExcludeAuthor` | List | Exclude mentions from selected authors or usernames. | `filterExcludeAuthor=spamaccount` |
| `filterIncludeHashtag` | List | Only return mentions containing selected hashtags. | `filterIncludeHashtag=launch,brand` |
| `filterExcludeHashtag` | List | Exclude mentions containing selected hashtags. | `filterExcludeHashtag=giveaway` |
| `filterIncludeDomain` | List | Only return results from selected domains. | `filterIncludeDomain=example.com` |
| `filterExcludeDomain` | List | Exclude results from selected domains. | `filterExcludeDomain=spam.example` |

### Kommon Poll Classification Filters

| Parameter | Type | Meaning | Example |
| --- | --- | --- | --- |
| `filterPriority` | List | Filter by Kommon Poll priority classification. | `filterPriority=high` |
| `filterTags` | List | Filter by Kommon Poll tags. | `filterTags=complaint,vip` |
| `filterSubTopics` | List | Filter by selected subtopic IDs. | `filterSubTopics=<subtopic-id>` |
| `filterIntents` | List | Filter by intent labels. | `filterIntents=purchase_intent` |
| `actionType` | List | Filter by supported action or content classifications. | `actionType=complaint` |

### Sentiment, Subjectivity, And Influence Ranges

| Parameter | Type | Meaning | Example |
| --- | --- | --- | --- |
| `minSent` | Number | Minimum sentiment or polarity value. | `minSent=0.2` |
| `maxSent` | Number | Maximum sentiment or polarity value. | `maxSent=-0.1` |
| `minSubj` | Number | Minimum subjectivity value. | `minSubj=0.5` |
| `maxSubj` | Number | Maximum subjectivity value. | `maxSubj=0.9` |
| `minInf` | Number | Minimum Kommon Poll influence score. | `minInf=50` |
| `maxInf` | Number | Maximum Kommon Poll influence score. | `maxInf=200` |

Minimum and maximum values are inclusive.

If both values are supplied for the same metric, the minimum cannot be greater than the maximum.

### Collection And Ingestion Date Filters

| Parameter | Accepted formats | Meaning |
| --- | --- | --- |
| `collectedDateFrom` | `YYYY-MM-DD`, `DDMMYY`, ISO datetime, epoch seconds, or epoch milliseconds | Earliest collection time. |
| `collectedDateTo` | Same | Latest collection time. |
| `ingestedDateFrom` | Same | Earliest ingestion time. |
| `ingestedDateTo` | Same | Latest ingestion time. |

Date-only values cover the full selected calendar date.

These filters are additional to `duration`. The `duration` parameter still controls the mention publication-date window.

Use collection and ingestion filters when analyzing when Kommon Poll received data rather than only when the source content was published.

### Multi-Value Parameters

Use comma-separated values.

Examples:

```text
platforms=facebook,instagram,youtube
filterLanguage=en,si,ta
filterIncludeDomain=example.com,example.org
```

URL-encode spaces and special characters.

---

## 5. Response Guide

`GET /v4/search` can return overview analytics, mention records, or both depending on the request parameters.

### Overview Response

Overview output uses the API response envelope and can include:

- Request execution metadata such as `took`, `timed_out`, and `_shards`.
- Total mention count in `hits.total.value`.
- Empty or populated `hits.hits`, depending on whether mention records were requested.
- Aggregate metric totals such as `socialReach_sum`, `interaction_sum`, `like_sum`, `comment_sum`, `share_sum`, and `view_sum`.
- Sentiment, subjectivity, reach, and influence stats.
- Platform, source, language, domain, date, author, hashtag, demographic, topic, intent, entity, and content breakdown buckets when present.

Anonymized shortened sample:

```json
{
  "took": 184,
  "timed_out": false,
  "_shards": {
    "total": 3,
    "successful": 3,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 128,
      "relation": "eq"
    },
    "max_score": null,
    "hits": []
  },
  "aggregations": {
    "socialReach_sum": {
      "value": 68420.0
    },
    "interaction_sum": {
      "value": 512.0
    },
    "like_sum": {
      "value": 306.0
    },
    "comment_sum": {
      "value": 94.0
    },
    "share_sum": {
      "value": 112.0
    },
    "view_sum": {
      "value": 68420.0
    },
    "unique_authors": {
      "value": 76
    },
    "unique_domains": {
      "value": 5
    },
    "polarity_counts": {
      "buckets": [
        {
          "key": "-1.1-0.0",
          "from": -1.1,
          "to": 0.0,
          "doc_count": 14
        },
        {
          "key": "0.0-1.0E-9",
          "from": 0.0,
          "to": 1e-9,
          "doc_count": 51
        },
        {
          "key": "1.0E-9-1.1",
          "from": 1e-9,
          "to": 1.1,
          "doc_count": 63
        }
      ]
    },
    "polarity_median": {
      "values": {
        "50.0": 0.0361
      }
    },
    "polarity_stats": {
      "count": 128,
      "min": -0.74,
      "max": 0.98,
      "avg": 0.2146,
      "sum": 27.4688
    },
    "subjectivity_median": {
      "values": {
        "50.0": 0.08
      }
    },
    "subjectivity_stats": {
      "count": 128,
      "min": 0.0,
      "max": 1.0,
      "avg": 0.1924,
      "sum": 24.6272
    },
    "influenceScore_stats": {
      "count": 128,
      "min": 0.82,
      "max": 112.4,
      "avg": 18.63,
      "sum": 2384.64
    },
    "group_by_platform": {
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 0,
      "buckets": [
        {
          "key": "facebook",
          "doc_count": 86,
          "group_by_hashtag": {
            "doc_count_error_upper_bound": 1,
            "sum_other_doc_count": 39,
            "buckets": [
              {
                "key": "ExampleLaunch",
                "doc_count": 12,
                "interaction_sum": {
                  "value": 65.0
                },
                "score_sum": {
                  "value": 121.79
                },
                "view_sum": {
                  "value": 16500.0
                }
              }
            ]
          },
          "group_by_authors": {
            "doc_count_error_upper_bound": 0,
            "sum_other_doc_count": 12,
            "buckets": [
              {
                "key": "sample_author",
                "doc_count": 8,
                "interaction_sum": {
                  "value": 24.0
                },
                "share_sum": {
                  "value": 4.0
                },
                "score_sum": {
                  "value": 84.42
                },
                "polarity_stats": {
                  "count": 8,
                  "min": -0.12,
                  "max": 0.66,
                  "avg": 0.28,
                  "sum": 2.24
                },
                "like_sum": {
                  "value": 16.0
                },
                "view_sum": {
                  "value": 3000.0
                },
                "comment_sum": {
                  "value": 4.0
                },
                "followers": {
                  "value": 0
                }
              }
            ]
          },
          "group_by_source": {
            "doc_count_error_upper_bound": 0,
            "sum_other_doc_count": 0,
            "buckets": [
              {
                "key": "facebook.com",
                "doc_count": 86,
                "interaction_sum": {
                  "value": 338.0
                },
                "share_sum": {
                  "value": 48.0
                },
                "score_sum": {
                  "value": 892.44
                },
                "polarity_stats": {
                  "count": 86,
                  "min": -0.74,
                  "max": 0.93,
                  "avg": 0.16,
                  "sum": 13.76
                },
                "like_sum": {
                  "value": 196.0
                },
                "view_sum": {
                  "value": 44200.0
                },
                "comment_sum": {
                  "value": 94.0
                },
                "followers": {
                  "value": 0
                }
              }
            ]
          }
        },
        {
          "key": "linkedin",
          "doc_count": 18,
          "group_by_source": {
            "doc_count_error_upper_bound": 0,
            "sum_other_doc_count": 0,
            "buckets": [
              {
                "key": "linkedin.com",
                "doc_count": 18,
                "interaction_sum": {
                  "value": 24.0
                },
                "share_sum": {
                  "value": 0.0
                },
                "score_sum": {
                  "value": 398.1
                },
                "like_sum": {
                  "value": 21.0
                },
                "view_sum": {
                  "value": 0.0
                },
                "comment_sum": {
                  "value": 3.0
                },
                "followers": {
                  "value": 32000
                }
              }
            ]
          }
        }
      ]
    },
    "group_by_domain": {
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 0,
      "buckets": [
        {
          "key": "facebook.com",
          "doc_count": 86
        },
        {
          "key": "linkedin.com",
          "doc_count": 18
        },
        {
          "key": "example-news.com",
          "doc_count": 7
        }
      ]
    },
    "languages": {
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 0,
      "buckets": [
        {
          "key": "en",
          "doc_count": 62,
          "polarity_stats": {
            "count": 62,
            "min": -0.43,
            "max": 0.98,
            "avg": 0.39,
            "sum": 24.18
          },
          "count": {
            "value": 62
          }
        },
        {
          "key": "si",
          "doc_count": 44,
          "polarity_stats": {
            "count": 44,
            "min": -0.21,
            "max": 0.82,
            "avg": 0.12,
            "sum": 5.28
          },
          "count": {
            "value": 44
          }
        }
      ]
    },
    "group_by_date": {
      "buckets": [
        {
          "key": "20260901",
          "doc_count": 42,
          "interaction_sum": {
            "value": 138.0
          },
          "daily_influence_sum": {
            "value": 842.7
          },
          "daily_social_Reach_sum": {
            "value": 22400.0
          },
          "daily_polarity_sum": {
            "value": 8.42
          },
          "daily_average_polarity": {
            "value": 0.2004
          },
          "daily_average_subjectivity": {
            "value": 0.1843
          },
          "daily_group_by_platform": {
            "doc_count_error_upper_bound": 0,
            "sum_other_doc_count": 0,
            "buckets": [
              {
                "key": "facebook",
                "doc_count": 31,
                "daily_platform_polarity_sum": {
                  "value": 5.91
                }
              },
              {
                "key": "linkedin",
                "doc_count": 6,
                "daily_platform_polarity_sum": {
                  "value": 2.28
                }
              }
            ]
          }
        }
      ]
    },
    "group_by_key_phrases": {
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 96,
      "buckets": [
        {
          "key": "Example Brand",
          "doc_count": 18
        },
        {
          "key": "customer experience",
          "doc_count": 11
        }
      ]
    },
    "cta": {
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 0,
      "buckets": [
        {
          "key": "none",
          "doc_count": 96,
          "cta_sub": {
            "doc_count_error_upper_bound": 0,
            "sum_other_doc_count": 0,
            "buckets": [
              {
                "key": "none",
                "doc_count": 96,
                "interaction_sum": {
                  "value": 244.0
                },
                "influenceScore_sum": {
                  "value": 1310.8
                },
                "polarity_avg": {
                  "value": 0.21
                },
                "socialReach_sum": {
                  "value": 32527.0
                }
              }
            ]
          }
        }
      ]
    },
    "persons": {
      "buckets": [
        {
          "key": "Sample Person A",
          "doc_count": 6
        }
      ]
    },
    "companies": {
      "buckets": [
        {
          "key": "Example Brand PLC",
          "doc_count": 48
        }
      ]
    },
    "products": {
      "buckets": [
        {
          "key": "Example Product",
          "doc_count": 9
        }
      ]
    },
    "events": {
      "buckets": [
        {
          "key": "Example Retail Forum 2026",
          "doc_count": 4
        }
      ]
    },
    "geolocations": {
      "buckets": [
        {
          "key": "Sample City",
          "doc_count": 12
        }
      ]
    }
  }
}
```

### Mention Response

Mention output can include:

- Request execution metadata such as `took`, `timed_out`, and `_shards`.
- Total matching count in `hits.total.value`.
- Individual records in `hits.hits`.
- Document metadata such as `_index`, `_id`, `_score`, and `sort`.
- Mention data under `_source`, including `sentiment`, `entities`, `author`, `time`, `source`, `metrics`, `contexts`, and `content`.
- Computed fields such as `fields.social_Reach` and `fields.influenceScore` when returned.
- Highlighted text fragments under `highlight` when returned.

Anonymized shortened sample:

```json
{
  "took": 36,
  "timed_out": false,
  "_shards": {
    "total": 3,
    "successful": 3,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 118,
      "relation": "eq"
    },
    "max_score": null,
    "hits": [
      {
        "_index": "mentions_v2",
        "_id": "https://www.linkedin.com/posts/example-publisher_sample-update-activity-1234567890-abcd",
        "_score": null,
        "_source": {
          "sentiment": {
            "subjectivity": 0.2,
            "polarity": 0.9517
          },
          "entities": {
            "persons": [
              "Sample Person A",
              "Sample Person B"
            ],
            "companies": [
              "Example Industry Association",
              "Example Brand PLC"
            ],
            "entity_sentiments": [
              {
                "sentiment": 0.4,
                "adjective": "informative",
                "entity": "Example Retail Forum 2026"
              }
            ],
            "locations": [
              "Sample City, Sample Country"
            ],
            "events": [
              "Example Retail Forum 2026"
            ]
          },
          "author": {
            "name": "Example Publisher"
          },
          "time": {
            "updated_at": "2026-09-02T01:38:09.839520+00:00",
            "published_day_of_week": "Tuesday",
            "ingested_at": "2026-09-01T15:23:05.466706+00:00",
            "published_at": "2026-09-01T16:08:34+00:00",
            "collected_at": "2026-09-01T15:23:05.466000+00:00"
          },
          "source": {
            "domain": "linkedin.com",
            "url": "https://www.linkedin.com/posts/example-publisher_sample-update-activity-1234567890-abcd",
            "platform": "linkedin"
          },
          "metrics": {
            "shares": 0,
            "comments": 0,
            "likes": 0
          },
          "contexts": [],
          "content": {
            "key_phrases": [
              "Example Retail Forum 2026",
              "customer experience",
              "AI"
            ],
            "post_type": "article",
            "language": {
              "code": "en",
              "confidence": 0.0
            },
            "text": "Example article text about a retail forum, technology adoption, customer experience, and market growth.",
            "clean": "Example article text about a retail forum technology adoption customer experience and market growth"
          }
        },
        "fields": {
          "social_Reach": [
            0
          ],
          "influenceScore": [
            98.0
          ]
        },
        "highlight": {
          "content.text": [
            "Example article text with a <span style='color:#23CBE0'>highlighted</span> search term."
          ]
        },
        "sort": [
          98.0,
          1788278914000
        ]
      },
      {
        "_index": "mentions_v2",
        "_id": "https://www.linkedin.com/posts/example-news_sample-market-update-activity-1234567891-wxyz",
        "_score": null,
        "_source": {
          "sentiment": {
            "subjectivity": 0.05,
            "polarity": 0.624
          },
          "entities": {
            "persons": [],
            "companies": [
              "Example Brand PLC"
            ],
            "entity_sentiments": [],
            "locations": [
              "Sample Market"
            ],
            "events": []
          },
          "author": {
            "name": "Example News Desk"
          },
          "time": {
            "updated_at": "2026-09-02T01:40:12.102000+00:00",
            "published_day_of_week": "Tuesday",
            "ingested_at": "2026-09-01T14:58:44.120000+00:00",
            "published_at": "2026-09-01T15:01:57+00:00",
            "collected_at": "2026-09-01T14:58:44.120000+00:00"
          },
          "source": {
            "domain": "linkedin.com",
            "url": "https://www.linkedin.com/posts/example-news_sample-market-update-activity-1234567891-wxyz",
            "platform": "linkedin"
          },
          "metrics": {
            "shares": 1,
            "comments": 2,
            "likes": 18
          },
          "contexts": [],
          "content": {
            "key_phrases": [
              "market update",
              "retail",
              "growth"
            ],
            "post_type": "post",
            "language": {
              "code": "en",
              "confidence": 0.0
            },
            "text": "Example post text summarizing a market update and related brand mentions.",
            "clean": "Example post text summarizing a market update and related brand mentions"
          }
        },
        "fields": {
          "social_Reach": [
            1200
          ],
          "influenceScore": [
            76.5
          ]
        },
        "highlight": {
          "content.text": [
            "Example post text with the matched <span style='color:#23CBE0'>brand</span> term."
          ]
        },
        "sort": [
          76.5,
          1788274917000
        ]
      }
    ]
  }
}
```

### Metric Interpretation

| Metric | Explanation |
| --- | --- |
| Mentions | Number of records matching the saved search, date range, and additional filters. |
| Interactions | Engagement activity associated with matching mentions, based on source data available to Kommon Poll. |
| Reach | Reach, view, or audience-related metric available for the result or aggregate. Do not describe it as unique people unless that is explicitly measured. |
| Influence | Kommon Poll's influence measure for prioritizing mentions or authors. Use the product-level definition rather than treating it as a universal industry score. |
| Sentiment or polarity | Direction and strength of detected sentiment. Use the Kommon Poll sentiment scale documented for your API version. |
| Subjectivity | Degree to which content is assessed as subjective rather than objective. |
| Unique authors | Distinct authors represented in the matching result set. |
| Unique domains | Distinct domains represented in matching web and news results. |
| Platform breakdown | Distribution of matching mentions by source or platform. |

### Data Caveats

- Not every platform provides every metric.
- A missing value should not automatically be interpreted as zero.
- Reach, engagement, and author metadata can differ by platform.
- A source post may later be deleted or made private even though Kommon Poll retains historical metadata.
- Publication time and collection or ingestion time represent different events and should be analyzed separately.
- API results reflect the original saved search plus any filters supplied in the request.
- When producing client-facing reports, state the reporting period and filters used.

---

## 6. Errors, Limits, And Retries

API clients should distinguish between requests that need to be corrected and temporary failures that can be retried.

Do not retry unchanged requests after `400`, `401`, `403`, or `404` responses.

### Status Codes

| Status | Meaning | Recommended developer action |
| --- | --- | --- |
| `200` | Successful request. | Process the response. |
| `400` | Invalid request, including missing `aid` or invalid parameter format. | Correct the request; do not retry unchanged. |
| `401` | Authentication failed. | Check the `Authorization` header and API key. |
| `403` | Authenticated key does not have access to the requested resource or feature. | Check the key's team, package, and access. |
| `404` | Saved search not found or not available to this key. | Use `GET /v4/list` and verify the `aid`. |
| `405` | Unsupported HTTP method. | Use `GET`. |
| `429` | Rate or usage limit reached, where applicable. | Retry using backoff and respect configured limits. |
| `500`, `502`, `503` | Temporary server or dependency error. | Retry transient failures with bounded exponential backoff. |

### Parameter Validation Examples

| Problem | Correct form |
| --- | --- |
| Missing `aid` | Add `?aid=<AID>`. |
| Invalid `duration` | Use `7d`, `30d`, or `DDMMYY-DDMMYY`. |
| Invalid `timerange` | Use `HHMM-HHMM`, such as `0900-1800`. |
| Invalid `timezone` | Use an IANA timezone such as `Asia/Colombo`. |
| Negative `dataFrom` | Use an integer greater than or equal to `0`. |
| `dataSize` over `500` | Paginate with `dataSize <= 500`. |
| Unsupported `sortBy` | Use a documented sort value. |
| Invalid numeric range | Ensure the minimum value is less than or equal to the maximum value. |

### Limits And Quotas

Key limits:

- `dataSize` is capped at `500` per request.
- Published request or rate limits should be followed when shown for your plan.
- API usage may be subject to plan-specific usage rules when configured.
- Large exports should paginate and checkpoint progress.

For dashboards, avoid re-downloading all mention pages when overview metrics are enough.

Use sensible caching for `GET /v4/list` and relatively static configuration data.

### Retry Guidance

Retry only transient failures:

- `429`
- `500`
- `502`
- `503`

Use:

- Explicit request timeouts.
- Bounded exponential backoff.
- Jitter to avoid synchronized retries.
- A maximum retry count.
- Logging that redacts the `Authorization` header.

Do not automatically retry:

- `400` without changing the request.
- `401` without correcting credentials.
- `403` without changing access or team configuration.
- `404` without verifying the `aid`.

---

## 7. Request Checklist

- Use a valid `aid` from `GET /v4/list`.
- Set `duration` explicitly for scheduled jobs.
- Set `timezone` when reporting periods should follow a local business day.
- Use `dataSize > 0` when you need mention records.
- Use `sortBy` for deterministic mention ordering.
- URL-encode timezone names, spaces, and special characters.
- Omit filters that are not needed.
- Keep `dataSize` at or below `500`.
- Paginate mention exports.
- Log request outcomes without logging secrets.
- Capture the `aid`, period, timezone, and filters used for each generated report.