post/search

Searches posts with filters, pagination, and sorting.

What is post search?

Post search is the main way to retrieve collected posts from a project. It combines the project scope with filters such as date range, platform, sentiment, tags, and text search, and returns a paginated result set.

Authentication

Authentication is required. See Authentication.

Permissions

Authentication is required.

Method and path

POST /post/search

Request headers

Header	Required	Description
X-Api-Key or X_API_KEY	yes	API key.
Content-Type	yes	application/json.
Cache-Control	no	Send no-cache to bypass the API cache for this request. In the PHP bootstrap this is read as HTTP_CACHE_CONTROL.

Request body

Field	Type	Required	Description
project_id	integer	yes	Project identifier.
limit	integer	no	Page size. Subject to server-side limits.
offset	integer	no	Pagination offset.
orderBy	string	no	Sort field. Default is post_time or engagement when engsort is set.
orderDir	string	no	Sort direction. Default DESC.
tab_id	integer	no	Cache invalidation scope.
debug	boolean	no	Debug toggle for query diagnostics.
Shared filters	mixed	no	Shared post filters such as date, platform, sentiment, priority, jobs, tags, language, author, and text search.

Example request

curl -X POST "$SIGNAL_API_BASE_URL/post/search" \
  -H "X-Api-Key: $SIGNAL_API_KEY" \
  -H "Cache-Control: no-cache" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": 123,
    "limit": 100,
    "offset": 0,
    "orderBy": "post_time",
    "orderDir": "DESC"
  }'

{
  "project_id": 123,
  "limit": 100,
  "offset": 0,
  "orderBy": "post_time",
  "orderDir": "DESC"
}

Example response

{
  "total": "<total_matches>",
  "cached": "<boolean>",
  "posts": [
    {
      "uuid": "<post_uuid>",
      "title": "<post_title>",
      "post_text": "<post_text>",
      "platform": "<platform_code>",
      "post_time": "<post_datetime>",
      "sentiment": "<sentiment>",
      "priority": "<priority>",
      "tags": ["<tag_id>"],
      "full_uri": "<post_url>"
    }
  ]
}

Response fields

Field	Type	Description
total	integer	Total number of matching posts.
posts	array<object>	Page of matched post documents.
cached	boolean	Present when the response is served from cache.

Post object fields

Field	Type	Description
uuid	string	Unique post identifier.
title	string	null
post_text	string	null
full_uri	string	null
platform	string	Platform code (tw, ig, fb, wn, etc.).
post_time	string	null
lang	string	null
sentiment	string	null
priority	integer	null
tags	array<string	integer>
Additional fields	mixed	Platform-specific fields can be included when available.

Notes

• Supports cache hits via API cache helpers.
• Cached responses include cached: true.
• To bypass the cache, send Cache-Control: no-cache; the V2 bootstrap checks this header via HTTP_CACHE_CONTROL before endpoint-level cache logic runs.