Skip to main content
GET
/
api
/
signals
/
analytics
/
keywords
List keyword analytics stats
curl --request GET \
  --url https://app.puffle.ai/api/signals/analytics/keywords \
  --header 'Authorization: Bearer <token>'
{
  "stats": [
    {
      "id": "aa111111-1111-1111-1111-111111111111",
      "user_id": "11111111-1111-1111-1111-111111111111",
      "signal_type_id": "bb111111-1111-1111-1111-111111111111",
      "source_id": "linkedin_jobs",
      "keyword": "VP Engineering",
      "raw_count": 250,
      "prefilter_count": 80,
      "validated_count": 42,
      "avg_confidence": 0.78,
      "avg_score": 62,
      "first_seen_at": "2026-03-01T10:00:00Z",
      "last_fetched_at": "2026-04-22T06:00:00Z",
      "last_produced_signal_at": "2026-04-21T10:30:00Z"
    }
  ],
  "nextOffset": 100
}

​
Overview

Returns per-(signal_type, source, keyword) performance metrics for the caller, sorted by raw_count descending. Each row aggregates every scan ever run for that keyword — use getKeywordRuns to see the per-run time series.

​
Filters

  • signal_type_id — narrow to one signal type.
  • source_id — narrow to one adapter (e.g. linkedin_jobs, reddit).

​
Pagination

Offset-based. offset defaults to 0, limit defaults to 100 and is capped at 500. The response sets nextOffset only when more rows exist.

​
AI agent notes

Interpretation. The keyword funnel is raw_count then prefilter_count then validated_count. Drops between stages identify where keywords are losing value — large raw-to-prefilter drops suggest noisy keywords; large prefilter-to-validated drops suggest the classifier is rejecting on-topic results (bad disqualifiers or prompt).Safe to poll. No side effects. Use during signal tuning to watch the effect of prompt or keyword changes.Chained call. Click into getKeywordRuns with a stat id to see the per-run snapshot history (last 100 runs, newest first).

Authorizations

​
Authorization
string
header
required

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

Query Parameters

​
signal_type_id
string<uuid>

Filter stats to a single signal type.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
​
source_id
string

Filter stats to a single adapter (e.g. linkedin_jobs).

​
offset
integer

Page offset. Defaults to 0.

Required range: 0 <= x <= 9007199254740991
​
limit
integer

Page size. Defaults to 100, capped at 500.

Required range: 1 <= x <= 500

Response

Page of keyword stats.

​
stats
object[]
required
​
nextOffset
integer

Offset to pass on the next page. Omitted when the final page has been returned.

Required range: 0 <= x <= 9007199254740991