Skip to main content
The scores endpoint returns the current lead score for a specific account or contact, giving you a real-time signal of how well a visitor matches your ideal customer profile and how engaged they are. Set include_history=true to retrieve the full scoring timeline — useful for tracking engagement trends or auditing score changes over time.

​
Endpoint

​
Required Scope

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

​
Parameters

​
string
The ID of the account whose score you want to retrieve. At least one of account_id or contact_id is required — a 400 is returned if neither is supplied.
​
string
The ID of the contact whose score you want to retrieve. At least one of account_id or contact_id is required.
​
boolean
default:"false"
When set to true, the response also includes data.history — all historical score records for the account or contact, in descending chronological order. When false (the default), only the current score is returned.
​
integer
default:"50"
The number of history records to return per page. Accepts values between 1 and 100. Only applies when include_history=true.
​
string
A pagination cursor returned in a previous response as next_cursor. Only applies when include_history=true.
​
string
Read a direct child tenant’s score 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 Requests

Retrieve the current score for an account:
Retrieve the current score plus full history for an account:

​
Response

Returns a ScoresResponse object. Unlike most other list-shaped endpoints, data here is not an array — it’s an object with a current score and an optional history array. Without include_history:
With include_history=true:

​
Response Fields

​
object
The account or contact’s current score.
​
array
Present only when include_history=true. An array of historical score records, most-recent first.
​
boolean
Only present when include_history=true. true if additional pages of history are available.
​
string | null
Only present when include_history=true. Pass this as cursor to retrieve the next page of history.

​
Error Responses

See Recent Scores (GET /v1/scores/recent) for a tenant-wide feed of score changes that doesn’t require an account_id/contact_id up front — useful for polling.