Skip to main content
GET
/
api
/
signals
/
feed
List signals in the feed
curl --request GET \
  --url https://app.puffle.ai/api/signals/feed \
  --header 'Authorization: Bearer <token>'
{ "signals": [ { "id": "aa111111-1111-1111-1111-111111111111", "source_id": "linkedin_jobs", "title": "Acme Corp is hiring a VP of Engineering", "label": "Hiring", "confidence": 0.92, "status": "new", "feedback": null, "signal_type_id": "bb111111-1111-1111-1111-111111111111", "color": "blue", "dismissed": false, "created_at": "2026-04-21T10:30:00Z", "normalized": { "url": "https://linkedin.com/jobs/view/123456", "company": "Acme Corp", "role": "VP of Engineering" }, "entity_company": "Acme Corp", "entity_person": null, "entity_id": "cc111111-1111-1111-1111-111111111111", "person_entity_id": null, "score": 87, "classification": { "reasoning": "Matches hiring signal type" }, "workflow_run": null } ], "has_more": true, "window_start": "2026-04-15T09:00:00Z" }

​
Overview

Returns the signal feed for the authenticated user. Two views are supported via the view query param:
  • view=signals (default) — a flat list of classified signals, newest first.
  • view=entities — signals grouped by entity (company or person), with per-entity aggregates (avg_score, signal_count, signal_type_breakdown) and up to 5 highest-scoring signals attached inline.
The window is defined by since (ISO-8601 upper bound, default: now) and days (lookback, default: 7, capped at 365). Dismissed signals and duplicates are excluded. has_more indicates whether older signals exist beyond window_start — widen days to retrieve them.

​
AI agent notes

Polling pattern. Safe to poll. No side effects, no cost. For a live feed, call every 1-5 minutes with days=1 to surface newly surfaced signals. The signal pipeline runs on a per-user cron — check the user’s preferred window via getScanTime.Status flow. Signals surface with status: "new". As the user interacts, status transitions to seen or is filtered out via dismissed=true. Dismissed signals are soft-deleted and never returned by this endpoint.View selection.
  • Use view=signals when building a chronological stream ranked by time or score.
  • Use view=entities when building an account-centric dashboard — one row per company/person with aggregated signal activity.
Follow-ups.
  • POST /api/signals/feed/{id}/feedback — record thumbs up/down.
  • POST /api/signals/feed/{id}/dismiss — hide the signal.
  • PUT /api/signals/scan-time — adjust when the next scan runs.

Authorizations

​
Authorization
string
header
required

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

Query Parameters

​
view
enum<string>

signals (default) returns a flat list of classified signals; entities returns signals grouped by company/person with aggregates.

Available options:
signals,
entities
​
since
string<date-time>

ISO-8601 upper bound for the time window. Defaults to now. Combined with days to produce the lookback window.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
​
days
integer

Number of days to look back from since. Defaults to 7. Clamped to the range 1-365.

Required range: 1 <= x <= 365

Response

Feed payload. Shape depends on view: signals array for view=signals, entities array for view=entities.

​
has_more
boolean
required

True when older signals/entities exist outside the current window — widen days to retrieve them.

​
window_start
string<date-time>
required

ISO-8601 lower bound of the window actually used.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
​
signals
object[]
​
entities
object[]
​
total
integer

Entity count when view=entities.

Required range: 0 <= x <= 9007199254740991