API Cookbooks

Outcome-oriented API recipes for reporting, dashboards, monitoring, intelligence, CX, media, BI, and AI-assisted workflows.

Use these cookbooks when you already have API access and want a practical request pattern for a business workflow.

Use MCP Recipes instead when the workflow should be conversational and the AI client should decide which Kommon Poll tools to call.

Each cookbook should record:

• Goal.
• When to use it.
• Prerequisites.
• Endpoint used.
• Request sequence.
• Parameters used.
• Example request.
• Response fields to inspect.
• Pagination considerations.
• Error handling.
• Security notes.
• Expected downstream output.
• Related reference pages.

1. Generate A Social Listening Report

Use this when a team needs a recurring or one-off report from a saved search.

Request sequence:

1. Use GET /v4/list to resolve the saved search.
2. Call GET /v4/search for the reporting period.
3. Use overview metrics for headline KPIs.
4. Retrieve representative mention pages for evidence and top examples.
5. Generate charts and narrative findings downstream.
6. Record the aid, period, timezone, and filters in the final methodology.

Useful parameters:

• duration
• timezone
• dataFrom
• dataSize
• sortBy
• maxSent
• platforms
• filterTags

2. Build A Monitoring Dashboard

Use this when an internal dashboard needs current Kommon Poll metrics.

Request sequence:

1. Store the monitored search aid.
2. Refresh overview metrics at a sensible interval.
3. Retrieve recent mentions with dataFrom=0, a positive dataSize, and sortBy=dateDesc.
4. Display volume, sentiment, reach, engagement, influence, and platform mix.
5. Cache responses to avoid unnecessary repeated calls.

For dashboards, avoid fetching full mention history when overview metrics or the first recent page are enough.

3. Scheduled Daily, Weekly, Or Monthly Report

Use this when reports should be generated automatically.

Request sequence:

1. Store the key securely on the server.
2. Store the selected aid in application configuration.
3. Run a scheduled GET /v4/search request using a fixed duration.
4. Create email, PDF, DOCX, slides, or BI outputs downstream.
5. Log request outcomes without logging the Authorization header.

Use local business time with timezone when the report should match a team reporting calendar.

4. Crisis And Reputation Monitoring

Use this when teams need fast visibility into an active incident, negative spike, fraud concern, outage, backlash, or reputation risk.

Request sequence:

1. Use a short duration, such as 1d or 7d.
2. Filter negative sentiment where appropriate.
3. Sort by dateDesc, engagementsDesc, or infDesc.
4. Filter priority, tags, or platforms if configured in the saved search workflow.
5. Surface representative mentions and key metrics for rapid review.

Useful requests:

GET /v4/search?aid=<AID>&duration=1d&maxSent=-0.01&dataFrom=0&dataSize=50&sortBy=dateDesc
GET /v4/search?aid=<AID>&duration=7d&maxSent=-0.01&dataFrom=0&dataSize=50&sortBy=infDesc

5. Competitor Intelligence

Use this when comparing a brand with competitors over the same reporting period.

Request sequence:

1. Use separate authorized saved searches for the brand and relevant competitors.
2. Use the same duration and timezone for every search.
3. Compare mention volume, sentiment, reach, engagement, influence, platforms, themes, and top mentions.
4. Persist normalized snapshots if historical benchmarking is required.

Keep the request logic identical across competitors so differences come from the data, not the integration.

6. Campaign Reporting

Use this when a launch, event, creator activation, or hashtag campaign has its own saved search.

Request sequence:

1. Use the campaign saved search aid.
2. Set explicit campaign dates where possible.
3. Filter by campaign hashtags, domains, authors, or platforms as required.
4. Report volume, sentiment, engagement, reach, top mentions, and audience response.

Example:

GET /v4/search?aid=<AID>&duration=010826-310826&filterIncludeHashtag=launch,brand&dataFrom=0&dataSize=50&sortBy=engagementsDesc

7. Voice Of Customer And CX Analysis

Use this when product, CX, or support teams need recurring issue discovery.

Request sequence:

1. Filter by complaint or action classifications, tags, intents, subtopics, and sentiment where configured.
2. Paginate matching mentions into the downstream analysis workflow.
3. Cluster recurring issues and quantify their occurrence downstream.
4. Keep mention IDs and source links for traceability.

Useful parameters:

• actionType
• filterTags
• filterIntents
• filterSubTopics
• maxSent
• dataFrom
• dataSize

8. Media And PR Monitoring

Use this when communications teams need a morning media brief or campaign media summary.

Request sequence:

1. Filter to the required platforms or domains.
2. Track mention volume, sentiment, influential coverage, and domain diversity.
3. Retrieve top coverage by influence, reach, or recency.
4. Generate a brief with source links and publication times.

Useful requests:

GET /v4/search?aid=<AID>&duration=1d&filterIncludeDomain=example.com,example.org&dataFrom=0&dataSize=50&sortBy=dateDesc
GET /v4/search?aid=<AID>&duration=7d&dataFrom=0&dataSize=50&sortBy=infDesc

9. High-Value Mention Feed

Use this when a CRM, outreach, or escalation workflow needs selected high-value mentions.

Request sequence:

1. Request individual mentions.
2. Sort by influence, engagement, reach, or recency.
3. Apply platform, sentiment, and priority filters.
4. Feed selected results into an approved outreach or CRM workflow.

Example:

GET /v4/search?aid=<AID>&duration=7d&filterPriority=high&dataFrom=0&dataSize=50&sortBy=reachDesc

10. Data Warehouse And BI Integration

Use this when Kommon Poll data should be joined with internal reporting data.

Request sequence:

1. Use GET /v4/list during configuration to map saved searches.
2. Ingest GET /v4/search data on a schedule.
3. Paginate mention datasets.
4. Preserve stable mention IDs and source URLs.
5. Store publication and collection or ingestion timestamps separately when returned.
6. Design the downstream schema to tolerate missing platform-specific fields.

Do not assume every platform returns the same metric set.

11. AI-Assisted Report Generation

Use this when a trusted backend prepares Kommon Poll context for an AI model.

Request sequence:

1. Call the Kommon Poll API from a trusted backend.
2. Pass selected aggregates and representative mentions to the chosen AI model.
3. Instruct the model to separate measured Kommon Poll metrics from interpretation and recommendations.
4. Keep source links and mention IDs in the generated output for traceability.
5. Do not expose the Kommon Poll API key to an untrusted client or browser.