Skip to main content
GET
/
api
/
signals
/
analytics
Get Analytics
curl --request GET \
  --url https://app.puffle.ai/api/signals/analytics \
  --header 'Authorization: Bearer <token>'
{
  "type": "keywords",
  "keywords": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "keyword": "<string>",
      "signalTypeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "sourceId": "<string>",
      "rawCount": 4503599627370495,
      "prefilterCount": 4503599627370495,
      "validatedCount": 4503599627370495,
      "avgConfidence": 123,
      "avgScore": 123
    }
  ],
  "pagination": {
    "cursor": "<string>",
    "hasMore": true,
    "count": 4503599627370495
  },
  "summaryAvgScore": {
    "avg": 123,
    "count": 4503599627370495
  }
}
CLI: 
puffle signal analytic --type <type>
puffle signal analytic --type <type> --signal-type-id <signal-type-id> --source-id <source-id> --min-score <min-score> --cursor <cursor> --limit <limit> --keyword-id <keyword-id>

​
Overview

Returns analytics on how each keyword is performing across past signal scans. The response shape is discriminated by the type query param:
  • type=keywords — cursor-paginated keyword stats across the caller’s types. Each row carries cumulative counts at every pipeline stage and the average score of validated signals. Filter by signalTypeId, sourceId, or minScore.
  • type=keyword-runs&keywordId={id} — bounded list of per-run snapshots for one keyword stat. Pagination is intentionally skipped because the history is small.
Use this to surface “which keywords are pulling their weight.” Agents can use it to prune keywords that produce volume but no validated signals.

​
AI agent notes

Pick the right type. Use keywords for a leaderboard. Use keyword-runs after picking one keyword from the leaderboard to drill into its history.Ownership-gated. keywordId is verified against the caller. Foreign or missing ids return 404.Score scale. Scores use the 1–3 sellability scale (1 = irrelevant, 3 = easy sell).Don’t loosen filters to “rescue” rejected items. Low keyword volume after the hard filter is the expected state for high-quality signals.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
type
enum<string>
required
Available options:
keywords,
keyword-runs
​
signalTypeId
string<uuid>
​
sourceId
string
​
minScore
integer
Required range: 0 <= x <= 3
​
cursor
string
​
limit
integer
Required range: 1 <= x <= 9007199254740991
​
keywordId
string<uuid>

Response

Analytics payload — shape depends on type.

​
type
enum<string>
required
Available options:
keywords
​
keywords
object[]
required
​
pagination
object
required

Cursor pagination envelope. cursor: null marks the last page.

​
summaryAvgScore
object