Skip to main content
GET
/
api
/
signals
Get Signals
curl --request GET \
  --url https://app.puffle.ai/api/signals \
  --header 'Authorization: Bearer <token>'
{
  "signals": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "signalTypeId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "signalTypeLabel": "<string>",
      "sourceId": "<string>",
      "score": 2,
      "title": "<string>",
      "excerpt": "<string>",
      "url": "<string>",
      "comment": "<string>",
      "dmText": "<string>",
      "commentText": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "classification": {},
      "authorName": "<string>",
      "authorUrl": "<string>",
      "entityCompany": "<string>",
      "entityPerson": "<string>",
      "groupKey": "<string>",
      "structuredWording": {
        "type": "hiring",
        "company": "<string>",
        "jobTitle": "<string>",
        "location": "<string>"
      },
      "formattedTitle": "<string>",
      "suggestedActions": [
        {
          "type": "copy_comment_and_open",
          "comment_text": "<string>"
        }
      ],
      "workflowRun": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "status": "<string>",
        "workflowId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      },
      "actionState": {},
      "color": "<string>",
      "label": "<string>",
      "entityId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "personEntityId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "entityDomain": "<string>",
      "entityMetadata": {
        "person": {},
        "company": {}
      },
      "normalized": {}
    }
  ],
  "pagination": {
    "cursor": "<string>",
    "hasMore": true,
    "count": 4503599627370495
  }
}
CLI: 
puffle signal
puffle signal --sort-by <sort-by> --group-by <group-by> --ids <ids> --since <since> --min-score <min-score> --include-dismissed --cursor <cursor> --limit <limit>

​
Overview

Returns the signal feed for the effective user, cursor-paginated. Dismissed signals are excluded by default. Use this endpoint to render the feed UI or to sync the workspace’s signals into an external system.

​
AI agent notes

Pass cursor from the previous response’s pagination.cursor to fetch the next page. Stop when pagination.hasMore is false.minScore filters on the 1–3 sellability scale (default 2). Pass 1 to include weak matches; pass 3 for the strongest matches only.Pass ids= (comma-separated UUIDs) to fetch a known set of signals in one page — this short-circuits cursor and limit.Pass includeDismissed=true to surface previously dismissed signals.Each signal row includes entityStatus and personEntityStatus — the workflow status of the resolved company and person entities ("new" | "contacted" | "dismissed"). These reflect lead-level state shared across all signals for that entity and are mutated via Update Signal Leads.

Authorizations

​
Authorization
string
header
required

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

Query Parameters

​
sortBy
enum<string>
Available options:
recency,
score
​
groupBy
enum<string>
Available options:
none,
person,
company
​
ids
string

Comma-separated signal ids. When present, ignores cursor/limit and returns the full requested set in one page.

​
since
string<date-time>
​
minScore
integer
Required range: 1 <= x <= 3
​
includeDismissed
boolean
​
cursor
string
​
limit
integer
Required range: 1 <= x <= 200

Response

Page of signals plus the next cursor (or null at end).

​
signals
object[]
required
​
pagination
object
required

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