Kenso
Start free

Social records

The Social records endpoints of the Kenso API.

1 endpointKen-Version: 1.1AuthenticationWorkspacesErrors

List social records

GET/v1/social-recordssocial-records.list

Needs the social_data feature on your workspace. Until it is on, calls answer 404.

Try it on developer.ken.so

The records stored for one contact, account or person (send exactly one of contactId, accountId and personId), newest read first. Free: it reads nothing new. kind keeps only those kinds (comma-separated), since only records read at or after that instant. Pages with limit (default 50, at most 200) and cursor, through the newest 1,000 records. Errors: 400 validation_failed, 404 for a contact, account or person outside this workspace. Needs Search view, and Campaigns view for a contact or Accounts view for an account or person (403 permission_denied).

Parameters

Name
In
Type
Required
Description
contactId
In: query
integer (int64)
optional
The contact whose linked records to list.
accountId
In: query
integer (int64)
optional
The account whose linked records to list.
personId
In: query
integer (int64)
optional
The person whose linked records to list.
kind
In: query
string
optional
Only these kinds, comma-separated: profile,post.
since
In: query
string (date-time)
optional
Only records Kenso read at or after this instant (UTC).
limit
In: query
integer (int32)
optional
Records per page, 1 to 200. Default 50.
cursor
In: query
string
optional
The nextCursor of the previous page.
Ken-Version
In: header
string, one of: 2026-11-02, 1.1
optional
The API version, a date in YYYY-MM-DD form. 1.1 is another name for the first dated version. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and 404 where the path exists only in this version. A date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy.
X-Ken-Workspace-Id
In: header
integer (int64)
optional
The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers 400 workspace_required. A workspace you are not a member of answers 404 not_found.

Response 200

data is a list of SocialRecord. Each item has these fields. The response also carries pagination.

Field
Type
Description
id
string
srec_ and the record's number.
platform
string
linkedin, facebook, instagram, x, tiktok, youtube or crunchbase.
kind
string
profile, company, channel, post, comment, job, review, event or ad.
url
string
The record's link on its platform.
externalId
string
The platform's own id for the record, when it has one.
handle
string
The username, page name or slug, when the record has one.
name
string
The person's, company's or channel's name, or a job's title.
text
string
A post's, comment's or review's text, or a profile's headline or about.
postedAt
string (date-time)
When a post, comment, job, review or ad was published, in UTC.
metrics
SocialMetrics
The counts the record reports about itself. A count the platform does not report is omitted.
data
map of JsonNode
Platform fields, which vary by platform: the full record as the platform reports it.
fetchedAt
string (date-time)
When Kenso read the record, in UTC.
Request
curl -X GET "https://api.ken.so/v1/social-records?limit=1" \
  -H "Authorization: Bearer $KEN_API_KEY" \
  -H "Ken-Version: 1.1" \
  -H "X-Ken-Workspace-Id: $KEN_WORKSPACE_ID"
Response 200
{
  "success": true,
  "data": [
    {
      "id": "string",
      "platform": "string",
      "kind": "string",
      "url": "https://example.com",
      "externalId": "string",
      "handle": "string",
      "name": "string",
      "text": "string",
      "postedAt": "2026-09-23T15:02:11Z",
      "metrics": {
        "followers": 1,
        "likes": 1,
        "comments": 1,
        "shares": 1,
        "views": 1
      },
      "data": {
        "key": {
          "options": {
            "propertyNameCaseInsensitive": true
          },
          "parent": {},
          "root": {}
        }
      },
      "fetchedAt": "2026-09-23T15:02:11Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6ODE1fQ",
    "hasMore": true,
    "total": 1,
    "isTotalCapped": true
  }
}
More in the API:Agent sandbox auto run settingsAgent sandbox connectionsAgent sandbox runsAgent workAgent work settingsAI feedbackBranching sequencesContact behaviorDeliverability rulesDelivery settingsLinkedIn job searchesLinkedIn jobsMessage templatesSaved list membersSequence importsSocial lookupsSocial resolutionsSocial searchesVoice note previewsVoice notesVoicesWhatsapp accountsWhatsapp settingsAll resources