# API Cookbooks > Apply the API to reporting, dashboards, crisis monitoring, competitor intelligence, CX, media monitoring, and BI workflows. > 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](/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: ```text GET /v4/search?aid=&duration=1d&maxSent=-0.01&dataFrom=0&dataSize=50&sortBy=dateDesc GET /v4/search?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: ```text GET /v4/search?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: ```text GET /v4/search?aid=&duration=1d&filterIncludeDomain=example.com,example.org&dataFrom=0&dataSize=50&sortBy=dateDesc GET /v4/search?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: ```text GET /v4/search?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.