---
title: "Get a contact's sentiment history"
method: GET
path: "/api/contacts/{contactId}/sentiment"
tags: ["Contacts"]
---

# Get a contact's sentiment history

`GET /api/contacts/{contactId}/sentiment`

## Request

- Base URL: `https://core-api.getaptly.com`
- URL: `https://core-api.getaptly.com/api/contacts/{contactId}/sentiment`
- Auth: one of:
  - API key in header `x-token`
  - API key in header `Authorization`
- TypeScript: <https://skmtc.dev/getaptly/apis/aptly-api/docs/api/contacts/:contactId/sentiment/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns the contact's conversation sentiment over the last 30 days, merged into a
single series across every channel in the company and keyed off the addresses in the
contact's `email` array.

One point per day, oldest first. `score` is the average of the day's streams — each
stream contributes one score, so a long conversation does not outweigh a short one —
rounded to a whole number on a 0-100 scale. `overall` is the recency-weighted average
across the window: today counts fully, a day at the edge of the window counts half.
`totalStreams` counts the distinct conversations in the window, so a conversation
spanning several days is counted once.

A contact with no email addresses, or with no scored conversations in the window,
returns `overall: null` and an empty `history`.

## Path parameters

- `contactId` string, required

## Response `200`

Sentiment history for the contact.

- object
  - `overall` integer, nullable: Recency-weighted average score (0-100) across the window.
  - `totalStreams` integer: Distinct conversations behind the window.
  - `history` object[]
    - `date` string, date-time
    - `score` integer: Average score (0-100) for the day.
    - `streams` integer: Distinct conversations behind the day.

## Other responses

- `401`: Invalid or missing API key.
- `404`: Contact not found.

---

[API](https://skmtc.dev/getaptly/apis/aptly-api.md) - [All operations](https://skmtc.dev/getaptly/apis/aptly-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getaptly/apis/aptly-api/revisions/75c367e0b8e5?raw)