GET /v4/list

Use GET /v4/list to discover saved searches and the aid values required by GET /v4/search.

GET /v4/list returns the search resources available to the authenticated API key.

Use this endpoint before GET /v4/search when an application needs to resolve a human-readable saved search to an aid.

It can also populate project or search selectors in external applications.

1. Request

Example:

curl https://api.kommonpoll.com/v4/list \
  -H "Authorization: Bearer YOUR_KOMMON_POLL_API_KEY"

2. Response Contents

The response can include:

• Saved searches available to the user.
• Saved searches available through the key's team.
• Recent search history.

Each saved search entry should include an aid. This value is the identifier required by GET /v4/search.

Applications should store the aid as the stable reference for search calls.

3. Sample Response

{
  "savedSearches": [
    {
      "aid": "brand-abc123",
      "title": "Acme Always-on Monitoring",
      "type": "My Brand",
      "updatedAt": "2026-08-31T10:12:00Z"
    }
  ],
  "teamSavedSearches": [
    {
      "aid": "campaign-def456",
      "title": "Launch Campaign",
      "type": "Campaign",
      "team": "Marketing",
      "updatedAt": "2026-08-30T08:45:00Z"
    }
  ],
  "recentHistory": [
    {
      "aid": "recent-ghi789",
      "title": "Weekend brand spike",
      "searchedAt": "2026-08-29T13:20:00Z"
    }
  ]
}

The exact fields returned can depend on the saved search and account context. The important integration field is aid.

4. Common Use Cases

• Populate a project selector in a reporting dashboard.
• Allow a user to choose which Kommon Poll saved search to analyze.
• Resolve a saved-search title to an aid during integration setup.
• Verify which searches are available to a specific API key.
• Discover the correct aid before a scheduled reporting job is configured.

5. Implementation Notes

• Cache the list response where appropriate.
• Refresh the list when a user changes team, creates a new saved search, or updates integration settings.
• Do not assume saved-search titles are unique.
• Use aid, not title, as the durable reference for search calls.
• Handle empty lists by checking the API key's team and API Access status.