List Recent Lead Score Changes Across Your Knock2 Tenant

Instead of polling individual account or contact scores, this endpoint gives you a tenant-wide feed of recent score changes — most recent first. Use it to power lightweight polling loops, seed Zapier triggers, or backfill your CRM whenever a new lead surpasses your qualification threshold.

Endpoint

GET https://api.knock2.ai/v1/scores/recent

Required Scope

Your API key must have the scores:read scope (or the broader all:read scope) to call this endpoint.

Parameters

integer

default:"50"

The number of score-change records to return per page. Accepts values between 1 and 100.

string

A pagination cursor returned in a previous response as next_cursor. Pass this value to retrieve the next page of results.

string

Read a direct child tenant’s score changes instead of your own (multi-tenant partners only). The X-Knock-Tenant header takes precedence if both are supplied. See Reading a Child Tenant’s Data.

string

Same as product_slug above, as a header instead of a query param. Naming a slug that isn’t a direct child of your key returns 404, never 403.

Example Request

curl https://api.knock2.ai/v1/scores/recent \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Returns a RecentScoresResponse object containing an array of score-change records sorted in descending order by created_at.

{
  "data": [
    {
      "id": "rsc_01HX...",
      "account_id": "acc_01HX...",
      "contact_id": null,
      "score": 91,
      "reason": "High engagement: 5 visits to /demo in 24 hours.",
      "created_at": "2024-06-02T08:15:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6InJzY18wMUhYIn0="
}

Response Fields

array

An array of recent score-change records, sorted most-recent first.

Show data[n] fields

string

A unique identifier for this score-change record. Use this field to deduplicate entries when polling the endpoint repeatedly.

string | null

The ID of the account whose score changed, or null if the change belongs to a contact.

string | null

The ID of the contact whose score changed, or null if the change belongs to an account.

integer

The new numeric lead score at the time of the change, from 0 to 100.

string

A human-readable explanation of what drove the score change.

string

ISO 8601 timestamp marking when this score change was recorded. Use this field for time-based filtering when building polling pipelines.

boolean

true if additional pages of results are available. Pass next_cursor in your next request to retrieve them.

string | null

A cursor string to retrieve the next page of results. null when there are no further pages.

Each entry in data mirrors the score.changed webhook payload, with id and created_at added for cursor-based pagination and deduplication. If you already use the score.changed webhook, the shape of each record will be familiar.

Error Responses

Status	Description
`401`	Missing or invalid API key.
`403`	Your API key does not have the `scores:read` scope.
`422`	The request is well-formed but contains semantic errors (e.g. an unprocessable parameter value).
`429`	Rate limit exceeded. Back off and retry.

Overview

Accounts

Contacts

Activity & Scores

Filter Sets

Webhooks

Enrichment & Auth

Tenants & Script

List Recent Lead Score Changes Across Your Knock2 Tenant

Endpoint

Required Scope

Parameters

Example Request

Response

Response Fields

Error Responses

​Endpoint

​Required Scope

​Parameters

​Example Request

​Response

​Response Fields

​Error Responses

Endpoint

Required Scope

Parameters

Example Request

Response

Response Fields

Error Responses