Engage Recommendations
Community threads and posts that AI answers cite for the prompts of a domain. Use them to find conversations to join.
curl --request GET \
--url 'https://api.aiclicks.io/api/v1/engage-recommendations?domain_id=8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3&platform=reddit&status=pending&sort_by=frequency&size=20' \
--header 'Authorization: Bearer ak_live_xxx'
import httpx, os
resp = httpx.get(
"https://api.aiclicks.io/api/v1/engage-recommendations",
params={
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3",
"platform": "reddit",
"status": "pending",
"size": 20,
},
headers={"Authorization": f"Bearer {os.environ['AICLICKS_API_KEY']}"},
)
resp.raise_for_status()
for row in resp.json()["data"]["items"]:
if row["is_brand_named"] is not True:
print(row["frequency"], row["title"], row["source_url"])
const url = new URL("https://api.aiclicks.io/api/v1/engage-recommendations");
url.searchParams.set("domain_id", "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3");
url.searchParams.append("topic_ids", "b7c1d2e3-4f50-4a6b-8c9d-0e1f2a3b4c5d");
const resp = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.AICLICKS_API_KEY}` },
});
const { data } = await resp.json();
console.log(data.counts_by_platform, data.pagination.total_count);
{
"data": {
"items": [
{
"id": "4e7a9c21-5b3d-4f60-8a1e-2c9d7b6f5e40",
"source_url": "https://www.reddit.com/r/smallbusiness/comments/1abc234/best_inventory_tools",
"source_domain": "reddit.com",
"title": "Best inventory tools for a small shop?",
"subtitle": "https://www.reddit.com/r/smallbusiness/comments/1abc234/best_inventory_tools",
"page_type": "Forums",
"platform": "reddit",
"frequency": 84,
"prompts_covered": 31,
"topics_covered": 6,
"status": "pending",
"note": null,
"created_at": "2026-08-17T02:02:11.504Z",
"updated_at": "2026-11-02T08:13:26.054Z",
"enrichment_status": "completed",
"snapshot_updated_at": "2026-10-21T02:20:16.934Z",
"archived": false,
"locked": false,
"metrics": {
"score": 42,
"upvote": 42,
"upvote_ratio": 0.96,
"total_comment": 57
},
"error_reason": null,
"removed": false,
"is_brand_named": false
}
],
"pagination": {
"current_page": 1,
"per_page": 20,
"total_count": 133,
"total_pages": 7,
"has_next": true,
"has_prev": false,
"last_page": false
},
"counts_by_platform": {
"reddit": 133,
"linkedin": 48,
"quora": 12,
"x": 3
}
},
"generated_at": "2026-11-09T10:00:11.218Z",
"domain_id": "8f1d3c0a-2f9b-4c11-9b80-7a82e1f0c3f3"
}
{
"detail": "Invalid or revoked API key"
}
{
"detail": "Domain not found"
}
{
"detail": "Too many requests. Please try again later."
}
This endpoint returns community threads and posts that AI answers cite for the prompts of a domain. The platforms include Reddit, X, LinkedIn, Quora, Facebook and Instagram. If you take part in these conversations, you can change what AI answers say.
Each row has the source URL, the title, the platform, and the number of AI answers that cite the page (frequency). Each row also has engagement metrics, a status and is_brand_named.
is_brand_named has three values:
true: the page is cited in the AI answers of the domain, and the page names the brand.false: the page is cited and checked, and the page does not name the brand.null: AIclicks has no citation analysis for the page.
You can filter by platform, status, topics, prompts and minimum engagement. The results are paginated.
The domain_id query parameter is required. To find the domains that your key can access, use GET /api/v1/domains.
Authorizations
Your API key formatted as Bearer ak_live_<your-key>. Create one in the dashboard under Settings → Developers.
Optional UUID for log correlation. If you do not send one, the server makes one and returns it in the response.
Query parameters
UUID of the domain. Find domains with GET /api/v1/domains.
Optional platform filter: reddit, x, linkedin, facebook, instagram, quora, …
Optional status filter: pending, done or dismissed.
Optional topic UUIDs from GET /api/v1/topics. To send more than one, repeat the parameter: topic_ids=a&topic_ids=b.
Optional prompt UUIDs from GET /api/v1/prompts. To send more than one, repeat the parameter.
Optional minimum engagement, for example the Reddit score. Minimum 0. Use it together with platform.
Optional minimum comment count. Minimum 0. Use it together with platform.
Sort column: frequency, engagement or comments. Defaults to frequency.
Sort direction: asc or desc. Defaults to desc.
1-indexed page number. Defaults to 1.
Rows per page, 1–100. Defaults to 50.
If true, the server ignores the cached result and calculates a new result. The new result replaces the cached result. Defaults to false.
Response
The recommendations page.
One row per thread or post.
current_page, per_page, total_count, total_pages, has_next, has_prev, last_page.
Number of rows for each platform, e.g. { "reddit": 133, "linkedin": 48 }.
Echo of the requested domain.
ISO-8601 timestamp of when the server made (or cached) this response.
Response headers
| Header | Description |
|---|---|
X-Cache | HIT, MISS, or REFRESH (when fresh=true). Tells you if the response came from cache. |
X-Request-Id | Unique request id. Echoes your id if you send one. |
X-RateLimit-Limit | Maximum requests per minute for this key. |
X-RateLimit-Remaining | Requests that remain in the current minute. |
X-RateLimit-Reset | Unix epoch seconds when the window resets. |
Caching
The server keeps the result in cache for 1 hour for each set of query parameters. If your team changes a status in the dashboard, the change shows after the cache expires. To get a new result, send fresh=true.
Errors
The API key is missing, not valid, or revoked.
The team's developer_access flag is off. Or the domain is not in the scope of your API key.
The domain_id is not valid or does not exist. Or your user is not a member of the domain's team.
The domain_id is missing. Or a parameter value is not allowed, for example sort_by=date or size=500.
You sent too many requests. The Retry-After header tells you how long to wait.
Empty result
If no row matches the filters, the endpoint returns 200. The items list is empty and total_count is 0.