Create an analysis from a content selection

curl -X POST https://api.siftsy.app/analyst/v1/analyses \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "selection": {
    "posts": {
      "account": "@acme",
      "platform": "tiktok",
      "posted_since": "2026-08-01"
    }
  },
  "filters": {
    "sentiment": [
      "negative",
      "lean_negative"
    ],
    "relevance": [
      "on_topic",
      "relevant"
    ],
    "replies": "exclude"
  }
}'

{
  "data": {
    "id": "an_5f2c9a1e0b6d4d0f9c1a2b3c4d5e6f70",
    "kind": "snapshot",
    "status": "ready",
    "createdAt": "2026-09-10T15:04:05.000Z",
    "updatedAt": "2026-09-10T15:04:05.400Z",
    "completedAt": "2026-09-10T15:04:05.400Z",
    "expiresAt": "2026-09-17T15:04:05.000Z",
    "selection": {
      "collectionId": "col_launch",
      "type": "collection",
      "status": "complete"
    },
    "filters": null,
    "search": null,
    "include": [
      "wordCloud"
    ],
    "postCount": 12,
    "postIds": [
      "p_301",
      "p_298",
      "p_290"
    ],
    "selectionTruncated": false,
    "scope": {
      "postCount": 12,
      "postIds": [
        "p_301",
        "p_298",
        "p_290"
      ],
      "totalComments": 4820,
      "matchedComments": 611,
      "matchedPosts": 11,
      "shareOfComments": 0.1268,
      "shareOfContent": 0.9167
    },
    "content": {
      "postCount": 12,
      "posts": [
        {
          "id": "p_301",
          "platform": "tiktok",
          "link": "https://www.tiktok.com/@acme/video/7311",
          "creator": {
            "username": "acme"
          },
          "postedAt": "2026-09-02T17:00:00.000Z",
          "matchedComments": 97
        }
      ],
      "postsTruncated": false,
      "topics": [
        {
          "title": "Product launch",
          "description": null,
          "postCount": 12
        }
      ],
      "messages": [
        {
          "topic": "Product launch",
          "stance": "The new line ships faster",
          "postCount": 8
        }
      ],
      "scores": {
        "content": 7.1,
        "topic": 6.4
      },
      "mix": {
        "content": {
          "positivePercent": 41,
          "leanPositivePercent": 22,
          "neutralPercent": 18,
          "leanNegativePercent": 11,
          "negativePercent": 8
        },
        "topic": {
          "positivePercent": 35,
          "leanPositivePercent": 27,
          "neutralPercent": 20,
          "leanNegativePercent": 10,
          "negativePercent": 8
        }
      }
    },
    "commentAnalysis": {
      "briefSummary": null,
      "scores": {
        "scoreVersion": 3,
        "siftsyScore": 3.4,
        "sentiment": 2.3,
        "relevance": 7.8,
        "consensus": 6.9,
        "content": 2.1,
        "topic": 2.6
      },
      "mix": {
        "sentiment": {
          "positivePercent": 0,
          "leanPositivePercent": 0,
          "neutralPercent": 0,
          "leanNegativePercent": 38,
          "negativePercent": 62
        },
        "content": {
          "positivePercent": 0,
          "leanPositivePercent": 2,
          "neutralPercent": 5,
          "leanNegativePercent": 40,
          "negativePercent": 53
        },
        "topic": {
          "positivePercent": 1,
          "leanPositivePercent": 3,
          "neutralPercent": 6,
          "leanNegativePercent": 41,
          "negativePercent": 49
        },
        "relevance": {
          "positivePercent": 58,
          "leanPositivePercent": 24,
          "neutralPercent": 9,
          "leanNegativePercent": 6,
          "negativePercent": 3
        },
        "consensus": {
          "positivePercent": 44,
          "leanPositivePercent": 31,
          "neutralPercent": 12,
          "leanNegativePercent": 9,
          "negativePercent": 4
        }
      },
      "topics": [],
      "outliers": [],
      "wordCloud": [
        {
          "text": "shipping",
          "value": 84,
          "type": "word",
          "avgSentiment": 2.1,
          "sentimentCategory": "negative",
          "mentionPercentage": 13.7
        },
        {
          "text": "never arrived",
          "value": 51,
          "type": "phrase",
          "avgSentiment": 1.8,
          "sentimentCategory": "negative",
          "mentionPercentage": 5.6
        }
      ],
      "emojiCloud": null,
      "totalComments": 611,
      "completeness": "scores_and_content",
      "notableComments": [
        {
          "postId": "p_301",
          "commentId": "c_77f1"
        },
        {
          "postId": "p_298",
          "commentId": "c_1a09"
        }
      ]
    },
    "comments": {
      "path": "/analyses/an_5f2c9a1e0b6d4d0f9c1a2b3c4d5e6f70/comments"
    },
    "computedAt": "2026-09-10T15:04:05.400Z"
  },
  "meta": {
    "status": "queued",
    "pollAfterMs": 1
  }
}

Requires analyses:run. Selection → analysis → comments. Name the content (selection.collectionId, selection.postIds, or selection.posts filters — the same filters as GET /posts, plus tag), optionally narrow the comments with dashboard filters and/or an AI search, and get back one analysis resource.

Snapshot (no AI search, ≤ 100 posts): computed inline from stored comment scores. Responds 201 with status: ready. search.mode: keyword is folded into filters.keywords and still returns a 201 snapshot.
Job (search with mode: ai — the default — or more than 100 posts): responds 202 with status: queued and a Location header. Poll GET /analyses/{analysisId} until status is ready or failed, honoring Retry-After / meta.pollAfterMs.

Either way, a sample of comments behind the analysis is GET /analyses/{analysisId}/comments. Analyses expire after 7 days.

Paths: the Location header is a path on the host (/analyst/v1/analyses/{analysisId}); comments.path in payloads is relative to the API base URL (/analyses/{analysisId}/comments). Do not prepend /analyst/v1 to comments.path a second time. Selections are capped at 1,000 posts (selectionTruncated: true when more matched). Never rescores posts or changes the workspace.

Rate class analysis_create (10 / minute, 100 / day per key), or analysis_search (2 / minute, 10 / day) when search.mode is ai. Recreate rollups on one refresh a day, not every run.

Requires `analyses:run`. **Selection → analysis → comments.** Name the content (`selection.collectionId`, `selection.postIds`, or `selection.posts` filters — the same filters as `GET /posts`, plus `tag`), optionally narrow the comments with dashboard `filters` and/or an AI `search`, and get back one analysis resource. - **Snapshot** (no AI `search`, ≤ 100 posts): computed inline from stored comment scores. Responds `201` with `status: ready`. `search.mode: keyword` is folded into `filters.keywords` and still returns a `201` snapshot. - **Job** (`search` with `mode: ai` — the default — or more than 100 posts): responds `202` with `status: queued` and a `Location` header. Poll `GET /analyses/{analysisId}` until `status` is `ready` or `failed`, honoring `Retry-After` / `meta.pollAfterMs`. Either way, a sample of comments behind the analysis is `GET /analyses/{analysisId}/comments`. Analyses expire after 7 days. Paths: the `Location` header is a path on the host (`/analyst/v1/analyses/{analysisId}`); `comments.path` in payloads is relative to the API base URL (`/analyses/{analysisId}/comments`). Do not prepend `/analyst/v1` to `comments.path` a second time. Selections are capped at 1,000 posts (`selectionTruncated: true` when more matched). Never rescores posts or changes the workspace. Rate class `analysis_create` (10 / minute, 100 / day per key), or `analysis_search` (2 / minute, 10 / day) when `search.mode` is `ai`. Recreate rollups on one refresh a day, not every run.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

X-Api-Keystring

API Key authentication via header

Request

This endpoint expects an object.

selectionobjectRequired

Which content the analysis covers. Provide exactly one of postIds or posts; collectionId may stand alone or be combined with posts filters to narrow within the collection. Resolves to at most 1,000 posts (newest first).

filtersobjectOptional

Comment-level narrowing — the same controls as the dashboard analysis view. Everything is optional; when present, only comments matching all active filters count toward the analysis and are returned from GET /analyses/{analysisId}/comments. Hidden comments are always excluded.

searchobjectOptional

Search inside the selected comments. mode: ai (default) runs the dashboard’s semantic search and always creates a job (202). mode: keyword is deterministic — it is folded into filters.keywords and stays synchronous.

includelist of enumsOptional

Optional extras computed with the analysis.

Allowed values:

Response headers

LocationstringOptional

Host path of the analysis, e.g. /analyst/v1/analyses/an_…

Response

Analysis computed inline (status: ready)

dataobjectOptional

An analysis created with POST /analyses. scope, content, and commentAnalysis are null until status is ready. content is creator-side (what was posted); commentAnalysis is audience-side (how the matched comments landed). A sample of comments behind the analysis lives at comments.path.

metaobjectOptional

Errors

400

Bad Request Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error