GET /v4/search

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

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

3. Request Examples

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

duration

Rolling duration format:

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:

HHMM-HHMM

Example:

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.

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

Source, Location, And Audience Filters

Author, Hashtag, And Domain Filters

Kommon Poll Classification Filters

Sentiment, Subjectivity, And Influence Ranges

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

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:

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:

{
  "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:

{
  "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

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

Parameter Validation Examples

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.