> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knock2.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Lead Scores for an Account or Contact — v1/scores

> GET /v1/scores returns the current lead score for an account or contact. Set include_history=true to retrieve the full score history in descending order.

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

```text theme={null}
GET https://api.knock2.ai/v1/scores
```

## Required Scope

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

## Parameters

<ParamField query="account_id" type="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.
</ParamField>

<ParamField query="contact_id" type="string">
  The ID of the contact whose score you want to retrieve. At least one of `account_id` or `contact_id` is required.
</ParamField>

<ParamField query="include_history" default="false" type="boolean">
  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.
</ParamField>

<ParamField query="limit" default="50" type="integer">
  The number of history records to return per page. Accepts values between `1` and `100`. Only applies when `include_history=true`.
</ParamField>

<ParamField query="cursor" type="string">
  A pagination cursor returned in a previous response as `next_cursor`. Only applies when `include_history=true`.
</ParamField>

<ParamField query="product_slug" type="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](/tenants/managing-tenants#reading-a-child-tenants-data).
</ParamField>

<ParamField header="X-Knock-Tenant" type="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`.
</ParamField>

## Example Requests

Retrieve the current score for an account:

```bash theme={null}
curl "https://api.knock2.ai/v1/scores?account_id=<account_id>" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Retrieve the current score plus full history for an account:

```bash theme={null}
curl "https://api.knock2.ai/v1/scores?account_id=<account_id>&include_history=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## 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`:

```json theme={null}
{
  "data": {
    "current": {
      "score": 82,
      "updated_at": "2024-06-01T14:30:00Z"
    }
  }
}
```

With `include_history=true`:

```json theme={null}
{
  "data": {
    "current": {
      "score": 82,
      "updated_at": "2024-06-01T14:30:00Z"
    },
    "history": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "score": 82,
        "reason": "Matches ICP: Series B, 50-200 employees, SaaS. 3 visits to /pricing.",
        "type": "icp_and_engagement",
        "created_at": "2024-06-01T14:30:00Z",
        "updated_at": "2024-06-01T14:30:00Z"
      }
    ]
  },
  "has_more": false,
  "next_cursor": null
}
```

### Response Fields

<ResponseField name="data.current" type="object">
  The account or contact's current score.

  <Expandable title="data.current fields">
    <ResponseField name="score" type="integer | null">
      The current numeric lead score, from `0` to `100`. `null` if the account/contact hasn't been scored yet.
    </ResponseField>

    <ResponseField name="updated_at" type="string | null">
      ISO 8601 timestamp of when the current score was last updated.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data.history" type="array">
  Present only when `include_history=true`. An array of historical score records, most-recent first.

  <Expandable title="data.history[n] fields">
    <ResponseField name="id" type="string">
      A unique identifier for this score record.
    </ResponseField>

    <ResponseField name="score" type="integer | null">
      The numeric lead score at this point in time.
    </ResponseField>

    <ResponseField name="reason" type="string | null">
      A human-readable explanation of why this score was assigned.
    </ResponseField>

    <ResponseField name="type" type="string | null">
      The scoring model/type that produced this record.
    </ResponseField>

    <ResponseField name="created_at" type="string | null">
      ISO 8601 timestamp marking when this score record was created.
    </ResponseField>

    <ResponseField name="updated_at" type="string | null">
      ISO 8601 timestamp marking when this score record was last updated.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="has_more" type="boolean">
  Only present when `include_history=true`. `true` if additional pages of history are available.
</ResponseField>

<ResponseField name="next_cursor" type="string | null">
  Only present when `include_history=true`. Pass this as `cursor` to retrieve the next page of history.
</ResponseField>

## Error Responses

| Status | Description                                         |
| ------ | --------------------------------------------------- |
| `400`  | Neither `account_id` nor `contact_id` was provided. |
| `401`  | Missing or invalid API key.                         |
| `403`  | Your API key does not have the `scores:read` scope. |
| `404`  | The specified account or contact was not found.     |
| `429`  | Rate limit exceeded. Back off and retry.            |

## Related

See [Recent Scores](/api-reference/scores/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.