URL: /code/data/social · Id: `page:/code/data/social`

# Social

> Read what buyers post on each Venue, who engaged with a post, and which accounts already hold your audience.

Read what buyers post on each Venue, who engaged with a post, and which accounts already hold your audience.

- **Noun:** [Post](https://startupbuilder.dev/business/nouns/post)
- **Calls:** 4
- **Emits:** `Post.found`, `Post.engagersFound`, `Handle.found`, `Handle.measured`

A Data Verb reads the market and returns a reading. A Software Verb changes your records and emits an Event. Every call here is a Data Verb: it reads, and it changes a record only where its Effects say so.

## Properties
| Field | Type | What `null` means |
| --- | --- | --- |
| `term` | `string` | Never null: the term as sent. |
| `venue` | [`VenueId`](/code/data/types#venueid) | Never null: the Venue read. |
| `posts` | `FoundPost[]` | Never null: empty when no post used the term in `within`, at $0. |
| `posts[].url` | `string` | Never null: the post’s own link. |
| `posts[].kind` | `'post' \| 'comment' \| 'video' \| 'question' \| 'issue'` | Never null: `video` on YouTube, TikTok and Instagram, `question` on Stack Overflow, `issue` on GitHub. |
| `posts[].title` | `string \| null` | The Venue gives posts no title: X, LinkedIn, TikTok, Instagram and comments. |
| `posts[].text` | `string \| null` | A link post or a video with no caption. |
| `posts[].author` | `{ handle: string; url: string \| null } \| null` | The account was deleted or is hidden. |
| `posts[].community` | `string \| null` | The Venue has no communities, or the post sits in none. |
| `posts[].publishedAt` | `string \| null`, in ISO 8601 | The Venue shows no date. |
| `posts[].engagement` | `{ score?: number; reactions?: number; comments?: number; shares?: number; views?: number }` | Never null. A count is absent where the Venue does not show it, never zero: LinkedIn shows no views. |
| `posts[]` | [`Observed`](/code/data/types#observed) | Each row also carries `observedAt`, `method` and `venue`. |
| `after` | [`Cursor`](/code/data/types#cursor) | The last page: there are no more rows. |
| `total` | `number \| null`, in posts | The Venue reports no total; most do not. |
| `cost` | [`Cost`](/code/data/types#cost), in USD | Never null. In try mode `usd` is 0 and `maxUsd` is what the call would have cost. |
| `post` | `{ url: string; venue: VenueId; engagement: { reactions?: number; comments?: number } }` | Never null: the post read, with its totals. |
| `engagers` | `Engager[]` | Never null: empty when no one engaged yet. |
| `engagers[].handle` | `string` | Never null: the account’s handle on the Venue. |
| `engagers[].name` | `string \| null` | The Venue shows a handle only: Reddit, X and TikTok often do. |
| `engagers[].headline` | `string \| null` | The Venue has no headline; LinkedIn is the one that does. |
| `engagers[].profileUrl` | `string \| null` | The account is hidden from people who are signed out, as some X and Instagram accounts are. |
| `engagers[].as` | `'reaction' \| 'comment'` | Never null. |
| `engagers[].reaction` | `string \| null` | A comment, or a Venue with one kind of reaction. |
| `engagers[].text` | `string \| null` | A reaction: only a comment has text. |
| `engagers[].at` | `string \| null`, in ISO 8601 | The Venue shows no time for a reaction. |
| `engagers[].organization` | `{ name: string; hostname: Hostname \| null } \| null` | No employer could be read from the profile. `Contact.enrich` fills it later. |
| `engagers[]` | [`Observed`](/code/data/types#observed) | Each row also carries `observedAt`, `method` and `venue`. |
| `handles` | `FoundHandle[]` | Never null: empty when nothing matched, at $0. |
| `handles[].handle` | `string` | Never null: `@smalllandlordmath`. |
| `handles[].name` | `string \| null` | The account shows no display name. |
| `handles[].url` | `string` | Never null. |
| `handles[].followers` | `number`, in followers or subscribers | Never null. |
| `handles[].engagementRate` | `number \| null`, in 0 to 1 | Fewer than 10 recent posts to average over. |
| `handles[].country` | `string \| null` | The account names no country. |
| `handles[].bio` | `string \| null` | The account has no bio. |
| `handles[].match` | `'filters' \| 'topic' \| 'both'` | Never null: which read found it. `both` is the strongest row. |
| `handles[]` | [`Observed`](/code/data/types#observed) | Each row also carries `observedAt`, `method` and `venue`. |
| `ignored` | `string[]` | Never null: a filter the Venue does not take, such as `keywords` on a described search. |
| `measures` | `Measure[]` | Never null: one row for each account read; a private or gone account is left out, free. |
| `measures[].handle` | `string` | Never null: the account as the Venue names it, `@smalllandlordmath`. |
| `measures[].followers` | `number \| null`, in followers or subscribers | The Venue counts none: Reddit. |
| `measures[].following` | `number \| null` | The Venue shows none: YouTube. |
| `measures[].postsRead` | `number`, in posts | Never null: the posts the averages are over. |
| `measures[].engagementRate` | `number \| null`, in 0 to 1: reactions and comments a post over followers, averaged | Fewer than 10 posts read, or no follower count. |
| `measures[].medianViews` | `number \| null`, in views a post | The Venue shows no views: LinkedIn, Reddit. |
| `measures[].cadence` | `{ postsPerWeek: number; lastPostAt: string \| null }` | Never null. `lastPostAt` is null for an account that never posted. |
| `measures[].topPosts` | `{ url: string; engagement: object }[]` | Never null: the three posts with the most engagement among those read. |
| `measures[]` | [`Observed`](/code/data/types#observed) | Each row also carries `observedAt`, `method` and `venue`. |

## Object
```json
{
  "url": "https://www.reddit.com/r/Landlord/comments/1kq9",
  "community": "r/Landlord",
  "score": 48,
  "comments": 31
}
```

## Verbs
| Verb | The question it answers | Price | Success rate |
| --- | --- | --- | --- |
| [`Post.find`](/code/data/social/find-posts) | Who is asking about my problem on Reddit, X or LinkedIn right now? | 19¢ per 100 searches | 99.4% of 147,547 calls |
| [`Post.findEngagers`](/code/data/social/find-engagers) | Who reacted to or commented on this post? | 0.3¢ a post | 99.95% of 44,205 calls |
| [`Handle.find`](/code/data/social/find-handles) | Which accounts already hold the audience I want? | 60¢ per 100 accounts | 99.91% of 12,814 calls |
| [`Handle.measure`](/code/data/social/measure-handles) | How big and how alive is this account? | 19¢ per 100 accounts | 99.9% of 413,075 calls |

## The order you call them in
1. [`Post.find`](/code/data/social/find-posts): Who is asking about my problem on Reddit, X or LinkedIn right now?
2. [`Post.findEngagers`](/code/data/social/find-engagers): Who reacted to or commented on this post?
3. [`Handle.find`](/code/data/social/find-handles): Which accounts already hold the audience I want?
4. [`Handle.measure`](/code/data/social/measure-handles): How big and how alive is this account?

## Monitors on this Noun
| Verb | What it watches |
| --- | --- |
| [`Post.find`](/code/data/social/find-posts) | New posts on Reddit, X and Hacker News that ask about your problem, daily; each new post records an Event. |
| [`Post.findEngagers`](/code/data/social/find-engagers) | New comments on a rival’s launch post, every 6 hours for 3 days. |
| [`Handle.measure`](/code/data/social/measure-handles) | A creator you sponsor, weekly: a drop of a fifth in engagement rate records an Event. |

## Works with
- **Workflows:** [Post-engager harvest](/capabilities/find-customers/post-engagers)
- **Agent tasks:** [Answer threads](/capabilities/publish-and-post/answer-threads) · [Launch day](/capabilities/earn-first-links/launch-day) · [Account brief](/capabilities/reach-out/account-brief) · [Message test](/capabilities/run-ads/message-test)