SquidX logo
Open SquidX

Leads

People your lead agents (automatic lead search on X) qualified against your ICP. A lead belongs to a list (each agent feeds one) and carries a relevance score, the reason the agent gave, and the signals that surfaced them. The DM campaigns that write to them are listed here too. The agents themselves have their own page.

List lead lists

GETsquidx.io/api/v1/lists
Requiresleads:read

The lists of the workspace. Use an id as the list filter below.

Request
curl https://squidx.io/api/v1/lists \
  -H "Authorization: Bearer sqx_your_key"
Response · 200
{
  "data": [
    {
      "id": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
      "name": "SquidX"
    }
  ]
}

List leads

GETsquidx.io/api/v1/leads
Requiresleads:read

Leads across the workspace's lists, newest first.

List leads parameters
NameInTypeDescription
listqueryuuidOnly leads of this list.
statusquerystringnew, contacted or archived.
minRelevancequeryintegerOnly leads scored at or above this, 0 to 100.
limitqueryintegerRows per page, 1 to 200. Default 50.
offsetqueryintegerRows to skip. Default 0. The response meta carries the total.
Request
curl "https://squidx.io/api/v1/leads?status=new&minRelevance=70" \
  -H "Authorization: Bearer sqx_your_key"
Response · 200
{
  "data": [
    {
      "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
      "leadId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "listId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
      "agentId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
      "status": "new",
      "relevance": 84,
      "reason": "Runs a two-person SaaS and asked how others find customers on X.",
      "addedAt": "2026-09-22T17:05:00.000Z",
      "profile": {
        "xUserId": "44196397",
        "handle": "janedoe",
        "url": "https://x.com/janedoe",
        "name": "Jane Doe",
        "bio": "Building a tiny SaaS. Sharing the numbers.",
        "avatarUrl": "https://pbs.twimg.com/profile_images/.../photo.jpg",
        "followers": 2310,
        "lastSignalAt": "2026-09-22T16:58:00.000Z"
      },
      "signals": [
        {
          "type": "keyword",
          "postId": "1969800012345678901",
          "at": "2026-09-22T16:58:00.000Z"
        }
      ]
    }
  ],
  "meta": {
    "total": 57,
    "limit": 50,
    "offset": 0
  }
}

Update a lead's status

PATCHsquidx.io/api/v1/leads/:id
Requiresleads:write

Mark a lead as new, contacted or archived. :id is the id GET /leads returns (the lead inside one list).

Update a lead's status parameters
NameInTypeDescription
statusrequiredbodystringnew, contacted or archived.
Request
curl -X PATCH https://squidx.io/api/v1/leads/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f \
  -H "Authorization: Bearer sqx_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "status": "contacted" }'
Response · 200
{
  "data": {
    "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
    "status": "contacted"
  }
}

List DM campaigns

GETsquidx.io/api/v1/campaigns
Requiresleads:read

The DM campaigns of the workspace with their list and send counts, newest first. Read only: campaigns start and stop in the dashboard.

Request
curl https://squidx.io/api/v1/campaigns \
  -H "Authorization: Bearer sqx_your_key"
Response · 200
{
  "data": [
    {
      "id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
      "name": "Founders September",
      "status": "active",
      "mode": "review",
      "list": {
        "id": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
        "name": "SquidX"
      },
      "sends": {
        "pending": 3,
        "queued": 2,
        "sent": 41,
        "skipped": 5,
        "failed": 0
      },
      "createdAt": "2026-09-01T10:00:00.000Z",
      "updatedAt": "2026-09-20T08:30:00.000Z"
    }
  ]
}