Skip to main content
Use this when you want to find, segment, or count posts across the full Crustdata social post dataset: who is talking about a topic, what a company page or a known person has published, which posts a target account was mentioned in, or which posts drew reactions and comments from a specific kind of person. This page walks you through the post record, your first search, the response shape, and choosing a search pattern, then folds in worked examples you can copy and adapt. For the filter grammar, the operator table, and the full field catalog, see Social Post Search reference.
Replace YOUR_API_KEY in each example with your actual API key. All requests require the x-api-version: 2025-11-01 header.
Enabled on request. This endpoint is off by default on every account and returns 403 until it is enabled. To turn it on, contact us. Check your entitlement at any time with GET /account/endpoints?path=/social_post/search.
Indexed, not live. This endpoint queries a periodically rebuilt index of posts. For the freshest posts by one person or company, use Enrich Social Posts. For a real-time keyword search, use Search Social Posts.

​
Post record mental model

Every result is one post object with these top-level groups:
  • Post identity and content: share_urn, share_url, text, post_type (original, repost_quote, or repost_without_thoughts), date_posted, hashtags, is_edited, and the URN family (backend_urn, entity_urn, parent_post_urn).
  • actor: the author, person or company, enriched with a Crustdata id, headline, current title and company_name, industry, and a structured location with city, state, country, and continent.
  • reposter: present on reposts. The account that reshared the post, with the same shape as actor.
  • engagement: total_reactions, total_comments, num_shares, and reactions_by_type with a count per reaction type.
  • reactors and comments: every reaction and comment on the post, each with the reacting or commenting person’s identity, title, company, and location. These arrays are returned in full and can be long.
  • mentions and hyperlinks: the Crustdata ids of people and companies mentioned in the post, plus the raw URLs the post links to.
  • Attachments: document, article, and poll objects, plus content_types, the list of attachment classes present on the post.
  • metadata: data_updated_at, when the post record was last updated.

​
At a glance

Examples

Company page posts, founders announcing a raise, posts mentioning a company, reactor and commenter targeting, and more.

Pagination and sorting

Sorting, cursor-based pagination, and field selection.

Reference

Filter grammar, operators, every filterable and sortable field, the response field catalog, and errors.

​
Request body

​
Response body

​
Rate limits and credits

Pricing: 0.5 credits per post returned. A request that returns no posts does not consume credits, and neither does a limit: 0 count query. The exact charge comes back in the X-Credits-Used header.
Default rate-limit is 30 requests per minute. Send an email to gtm@crustdata.co to discuss higher limits if needed for your use case.

​
Your first search: a keyword from authors in one city

Find people in Kolkata whose posts mention Rust, newest first. [.] on text is an exact-phrase match, the right tool for a short technical keyword. The fuzzy (.) operator would also match “just”, “must”, and “trust”.
The post text, picture URLs, and cursor are shortened here. Notice that actor fields such as company_name and title appear only when the author record carries them, so read every actor field as optional.

​
Which search pattern should I use?

Use Social Post Search. Slice hundreds of millions of indexed posts by text, author attributes, engagement, reactor and commenter attributes, mentions, or attachment type, and walk large result sets with cursor pagination.

​
Examples

Worked recipes you can copy, paste, and adapt. Each example is a full working request paired with the response it returned. Responses are trimmed to the fields under discussion, and long text and cursors are shortened. For the filter grammar, operators, and the full field catalog, see Social Post Search reference.
Filter on actor.crustdata_entity_id with the company’s Crustdata id and sort newest first. Person ids and company ids are separate id spaces, so add actor.actor_type = company when you want to rule out a person with the same number.
Combine an exact phrase on text with a fuzzy title match and a date floor, then sort by engagement.total_reactions.
mentions.company_id holds the Crustdata ids resolved from the company pages a post links to. Use it to find who is talking about a target account. The matching raw URLs sit in hyperlinks.company_professional_network_urls.
hashtags is an array field, so in matches a post carrying any of the listed tags. Sort by engagement.total_comments to surface the posts that drew the most replies.
Conditions on reactors.* inside one and group bind to the same reactor: a founder whose reaction was specifically PRAISE. The comments.title condition is evaluated independently against the commenters. See Nested-array matching for the cross-element form.
reactors and comments come back in full. This post carries 2,750 reactors and 320 comments. Request these arrays only when you need them.
The response is cut to the first two reactors and the first comment. The arrays hold every reactor and commenter, not only the ones that matched, so filter them client-side when you need the matching elements.
content_type is a filter-only field that matches posts carrying a given attachment class: document, article, poll, video, or image. The matching attachment comes back in its own object.
geo_distance on actor.location keeps posts whose author is located within the radius. The server geocodes the location string, or pass lat_lng to skip that step. Hashtag matching is case-insensitive.
Set limit to 0. The response carries total_count only, and the request costs nothing.
Send the same body again with cursor set to the previous next_cursor. Keep filters, sorts, and fields identical between pages.

​
What to do next