---
title: "Get social content state"
method: GET
path: "/api/apps/{app_id}/virality/state"
---

# Get social content state

`GET /api/apps/{app_id}/virality/state`

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Returns everything stored for the app's social content flow: how far it has got, the questions and your answers, the current strategy, and the content plan.

Read `stage` to see where the app is. An app that never started the flow returns `stage` of `idle` and `null` for everything else, rather than a 404.

Poll this endpoint after [Generate content plan](/api-reference/generate-content-plan) returns. Only the first platform's images are generated inline, so the rest of the `image_url` values appear here as they finish. A `stage` of `generating` means a plan is still being built, and the endpoints that change the plan fail with a 409 until it finishes.

This endpoint is limited to 40 requests per minute, separately from the other social content endpoints.

<Note>This endpoint accepts a personal API key. Workspace API keys are not authorized for it and are rejected with a 403.</Note>

<Warning>The response may include fields beyond the ones documented here. Don't use any undocumented fields, as they can change at any time.</Warning>

## Path parameters

- `app_id` string, required — ID of the app.

## Response `200`

The app's social content state.

- SocialContentStateResponse
  - `stage` 'idle' | 'questions' | 'strategy' | 'generating' | 'completed'
  - `questions` ViralityQuestion[], nullable — Questions from [Start social content flow](/api-reference/start-social-content-flow), or `null` if the flow hasn't started.
    - `id` string, nullable — ID of the question. Use it as the key in the `answers` object you pass to [Submit answers](/api-reference/submit-answers).
    - `question` string, nullable — Question text to show the user.
    - `type` string, nullable — How to collect the answer. `select` offers the listed `options`, `text_input` takes free text.
    - `options` ViralityQuestionOption[], nullable — Options to choose from on a `select` question, or `null` on a `text_input` question.
      - `label` string, nullable — Answer option to show the user. Send this value back as the answer for a `select` question.
      - `description` string, nullable — Short clarification of what this option means, or `null` if none was generated.
    - `placeholder` string, nullable — Hint text for a `text_input` question, or `null` when there is none.
  - `analysis_text` string, nullable — One-sentence analysis of the app, or `null` if the flow hasn't started.
  - `answers` object, nullable — Answers you submitted, keyed by question `id`, or `null` if none were submitted.
  - `strategy_text` string, nullable — The current content strategy, or `null` if none was generated.
  - `plan` ContentPlan
    - `id` string, nullable — ID of the content plan.
    - `app_id` string, nullable — ID of the app the plan belongs to.
    - `strategy` ContentStrategy
      - `app_summary` string, nullable — Short summary of what the app does.
      - `marketing_approach` string, nullable — The approach the content takes, extracted from the accepted strategy. Empty if the strategy text was empty when the plan was generated.
      - `platforms` PlatformContentPlan[] — One entry per platform you approved, in the order you sent them.
        - `platform` 'x' | 'instagram' | 'tiktok' | 'linkedin' | 'reddit' | 'facebook'
        - `mode` 'series' | 'selection'
        - `reasoning` string, nullable — Why the content for this platform takes the shape it does.
        - `posts` SocialPost[] — The generated posts for this platform.
          - `id` string, nullable — ID of the post. Pass it as `post_id` to [Refine a post](/api-reference/refine-a-post), [Update post content](/api-reference/update-post-content), and [Generate a post image](/api-reference/generate-a-post-image).
          - `platform` 'x' | 'instagram' | 'tiktok' | 'linkedin' | 'reddit' | 'facebook'
          - `angle` 'pain_point' | 'feature_demo' | 'social_proof' | 'trending_hook' | 'user_story' | 'before_after'
          - `angle_label` string, nullable — Human-readable label for the angle.
          - `post_number` integer, nullable — Position of this post within its platform's set, starting at 1.
          - `total_posts` integer, nullable — Number of posts generated for this platform.
          - `suggested_day` integer, nullable — Suggested day to publish on, counted from the start of the campaign.
          - `rationale` string, nullable — Why this post works for this platform and angle.
          - `content` string, nullable — The post text, ready to publish. Change it with [Update post content](/api-reference/update-post-content).
          - `image_url` string, nullable — URL of the post image, or `null` if no image was generated yet. Create one with [Generate a post image](/api-reference/generate-a-post-image).
          - `image_prompt` string, nullable — Prompt used to generate the post image, or `null` if the post has none.
          - `hashtags` string[], nullable — Suggested hashtags, without the leading `#`.
          - `post_title` string, nullable — Title for platforms that use one, such as Reddit and LinkedIn. `null` elsewhere.
          - `suggested_subreddits` string[], nullable — Subreddits to consider for a Reddit post. Empty for other platforms.
          - `launch_comment` string, nullable — First comment to post under the main post, or `null` if none was generated.
          - `option_label` string, nullable — Label for this post when the platform's `mode` is `selection`, so you can tell the alternatives apart. `null` in `series` mode.
          - `best_for_context` string, nullable — When to prefer this option over the others, or `null` if not applicable.
    - `created_at` string, nullable — Time the plan was created, as an ISO 8601 timestamp.
    - `updated_at` string, nullable — Time the plan last changed, as an ISO 8601 timestamp.
  - `builder_handle` string, nullable — Social handle taken from the `social_url` you submitted, or `null` if you never sent one.
  - `app_name` string, nullable — Name of the app.
  - `teaser` TeaserSummary — The wizard-free posts shown on the Marketing home. Separate from `plan` because they are not part of one — see `teaser.py`. The model the reference renders and the one the routes return: two of these drifted apart once already, so `GET /state` and `POST /teaser` both build this rather than a runtime twin of it.
    - `status` 'generating' | 'ready' | 'failed'
    - `post` SocialPost
      - `id` string, nullable — ID of the post. Pass it as `post_id` to [Refine a post](/api-reference/refine-a-post), [Update post content](/api-reference/update-post-content), and [Generate a post image](/api-reference/generate-a-post-image).
      - `platform` 'x' | 'instagram' | 'tiktok' | 'linkedin' | 'reddit' | 'facebook'
      - `angle` 'pain_point' | 'feature_demo' | 'social_proof' | 'trending_hook' | 'user_story' | 'before_after'
      - `angle_label` string, nullable — Human-readable label for the angle.
      - `post_number` integer, nullable — Position of this post within its platform's set, starting at 1.
      - `total_posts` integer, nullable — Number of posts generated for this platform.
      - `suggested_day` integer, nullable — Suggested day to publish on, counted from the start of the campaign.
      - `rationale` string, nullable — Why this post works for this platform and angle.
      - `content` string, nullable — The post text, ready to publish. Change it with [Update post content](/api-reference/update-post-content).
      - `image_url` string, nullable — URL of the post image, or `null` if no image was generated yet. Create one with [Generate a post image](/api-reference/generate-a-post-image).
      - `image_prompt` string, nullable — Prompt used to generate the post image, or `null` if the post has none.
      - `hashtags` string[], nullable — Suggested hashtags, without the leading `#`.
      - `post_title` string, nullable — Title for platforms that use one, such as Reddit and LinkedIn. `null` elsewhere.
      - `suggested_subreddits` string[], nullable — Subreddits to consider for a Reddit post. Empty for other platforms.
      - `launch_comment` string, nullable — First comment to post under the main post, or `null` if none was generated.
      - `option_label` string, nullable — Label for this post when the platform's `mode` is `selection`, so you can tell the alternatives apart. `null` in `series` mode.
      - `best_for_context` string, nullable — When to prefer this option over the others, or `null` if not applicable.
    - `posts` SocialPost[] — The teaser posts, one per platform. A regeneration keeps the posts it is replacing, so these can be set while `status` is `generating`.
      - `id` string, nullable — ID of the post. Pass it as `post_id` to [Refine a post](/api-reference/refine-a-post), [Update post content](/api-reference/update-post-content), and [Generate a post image](/api-reference/generate-a-post-image).
      - `platform` 'x' | 'instagram' | 'tiktok' | 'linkedin' | 'reddit' | 'facebook'
      - `angle` 'pain_point' | 'feature_demo' | 'social_proof' | 'trending_hook' | 'user_story' | 'before_after'
      - `angle_label` string, nullable — Human-readable label for the angle.
      - `post_number` integer, nullable — Position of this post within its platform's set, starting at 1.
      - `total_posts` integer, nullable — Number of posts generated for this platform.
      - `suggested_day` integer, nullable — Suggested day to publish on, counted from the start of the campaign.
      - `rationale` string, nullable — Why this post works for this platform and angle.
      - `content` string, nullable — The post text, ready to publish. Change it with [Update post content](/api-reference/update-post-content).
      - `image_url` string, nullable — URL of the post image, or `null` if no image was generated yet. Create one with [Generate a post image](/api-reference/generate-a-post-image).
      - `image_prompt` string, nullable — Prompt used to generate the post image, or `null` if the post has none.
      - `hashtags` string[], nullable — Suggested hashtags, without the leading `#`.
      - `post_title` string, nullable — Title for platforms that use one, such as Reddit and LinkedIn. `null` elsewhere.
      - `suggested_subreddits` string[], nullable — Subreddits to consider for a Reddit post. Empty for other platforms.
      - `launch_comment` string, nullable — First comment to post under the main post, or `null` if none was generated.
      - `option_label` string, nullable — Label for this post when the platform's `mode` is `selection`, so you can tell the alternatives apart. `null` in `series` mode.
      - `best_for_context` string, nullable — When to prefer this option over the others, or `null` if not applicable.

## Other responses

- `401` — Missing or invalid credentials.
- `403` — You don't have editor access to this app, or you used a workspace API key.
- `404` — App not found, or the social content feature is not enabled for your account.
- `422` — Validation Error
- `429` — Rate limit exceeded (40 requests per minute).
- `500` — Loading the state failed. Retry the request.

## Changes

- **2026-08-26** `f2727732ced1` — 1 breaking, 4 info
  - the `teaser` response's property type/format changed from ``/`` to `object`/`` for status `200`
  - added the optional property `teaser/post` to the response with the `200` status
  - added the optional property `teaser/posts` to the response with the `200` status
  - added the optional property `teaser/status` to the response with the `200` status
  - …1 more
- **2026-08-25** `8dfd9c46c0b9` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/idealspot/apis/base44-app-management-api/changes/api/apps/:app_id/virality/state/get.md)

---

[API](https://skmtc.dev/idealspot/apis/base44-app-management-api.md) · [All operations](https://skmtc.dev/idealspot/apis/base44-app-management-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/idealspot/base44-app-management-api/revisions/31ef75eb64ab/schema)