> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get social content 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>



## OpenAPI

````yaml /developers/references/app-management/app-management-openapi.json get /api/apps/{app_id}/virality/state
openapi: 3.1.0
info:
  title: Base44 App Management API
  version: 1.0.0
servers:
  - url: https://app.base44.com
security:
  - ApiKeyAuth: []
paths:
  /api/apps/{app_id}/virality/state:
    get:
      summary: Get social content state
      description: >-
        <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>
      operationId: get_virality_state_api_apps__app_id__virality_state_get
      parameters:
        - name: app_id
          in: path
          required: true
          schema:
            type: string
            description: ID of the app.
            title: App Id
          description: ID of the app.
          example: 6820f3a4e7b91d003c45a1f2
      responses:
        '200':
          description: The app's social content state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SocialContentStateResponse'
        '401':
          description: Missing or invalid credentials.
        '403':
          description: >-
            You don't have editor access to this app, or you used a workspace
            API key.
        '404':
          description: >-
            App not found, or the social content feature is not enabled for your
            account.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate limit exceeded (40 requests per minute).
        '500':
          description: Loading the state failed. Retry the request.
components:
  schemas:
    SocialContentStateResponse:
      properties:
        stage:
          anyOf:
            - $ref: '#/components/schemas/ViralityStage'
            - type: 'null'
          description: >-
            How far the app has got. `idle` before you start, then `questions`,
            `strategy`, `generating`, and `completed` once a plan exists.
          example: completed
        questions:
          anyOf:
            - items:
                $ref: '#/components/schemas/ViralityQuestion'
              type: array
            - type: 'null'
          title: Questions
          description: >-
            Questions from [Start social content
            flow](/api-reference/start-social-content-flow), or `null` if the
            flow hasn't started.
        analysis_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Analysis Text
          description: >-
            One-sentence analysis of the app, or `null` if the flow hasn't
            started.
          example: A CRM for freelancers who want to track leads without a spreadsheet.
        answers:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Answers
          description: >-
            Answers you submitted, keyed by question `id`, or `null` if none
            were submitted.
          example:
            goal: Get the first 100 users
        strategy_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Strategy Text
          description: The current content strategy, or `null` if none was generated.
          example: Lead with the spreadsheet pain, then show the app solving it.
        plan:
          anyOf:
            - $ref: '#/components/schemas/ContentPlan'
            - type: 'null'
          description: >-
            The current content plan, or `null` if none was generated. Poll this
            to pick up images that finish generating after [Generate content
            plan](/api-reference/generate-content-plan) returns.
        builder_handle:
          anyOf:
            - type: string
            - type: 'null'
          title: Builder Handle
          description: >-
            Social handle taken from the `social_url` you submitted, or `null`
            if you never sent one.
          example: '@yourhandle'
        app_name:
          anyOf:
            - type: string
            - type: 'null'
          title: App Name
          description: Name of the app.
          example: Freelance CRM
        teaser:
          anyOf:
            - $ref: '#/components/schemas/TeaserSummary'
            - type: 'null'
          description: >-
            The standalone teaser post, which is generated outside this flow and
            is not part of `plan`.
      type: object
      title: SocialContentStateResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ViralityStage:
      type: string
      enum:
        - idle
        - questions
        - strategy
        - generating
        - completed
      title: ViralityStage
    ViralityQuestion:
      properties:
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
          description: >-
            ID of the question. Use it as the key in the `answers` object you
            pass to [Submit answers](/api-reference/submit-answers).
          example: goal
        question:
          anyOf:
            - type: string
            - type: 'null'
          title: Question
          description: Question text to show the user.
          example: What does success look like for this app?
        type:
          anyOf:
            - type: string
            - type: 'null'
          title: Type
          description: >-
            How to collect the answer. `select` offers the listed `options`,
            `text_input` takes free text.
          example: select
        options:
          anyOf:
            - items:
                $ref: '#/components/schemas/ViralityQuestionOption'
              type: array
            - type: 'null'
          title: Options
          description: >-
            Options to choose from on a `select` question, or `null` on a
            `text_input` question.
        placeholder:
          anyOf:
            - type: string
            - type: 'null'
          title: Placeholder
          description: Hint text for a `text_input` question, or `null` when there is none.
          example: https://x.com/yourhandle
      type: object
      title: ViralityQuestion
    ContentPlan:
      properties:
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
          description: ID of the content plan.
          example: 8c1f9a2e-3b7d-4c5e-9f01-2a3b4c5d6e7f
        app_id:
          anyOf:
            - type: string
            - type: 'null'
          title: App Id
          description: ID of the app the plan belongs to.
          example: 6820f3a4e7b91d003c45a1f2
        strategy:
          anyOf:
            - $ref: '#/components/schemas/ContentStrategy'
            - type: 'null'
          description: The strategy and the per-platform posts.
        created_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Created At
          description: Time the plan was created, as an ISO 8601 timestamp.
          example: '2026-08-24T09:15:00+00:00'
        updated_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Updated At
          description: Time the plan last changed, as an ISO 8601 timestamp.
          example: '2026-08-24T10:02:00+00:00'
      type: object
      title: ContentPlan
    TeaserSummary:
      properties:
        status:
          anyOf:
            - $ref: '#/components/schemas/TeaserStatus'
            - type: 'null'
          description: >-
            Status of the standalone teaser post, or `null` if none was ever
            requested for this app.
          example: ready
        post:
          anyOf:
            - $ref: '#/components/schemas/SocialPost'
            - type: 'null'
          description: The teaser post, or `null` unless `status` is `ready`.
      type: object
      title: TeaserSummary
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ViralityQuestionOption:
      properties:
        label:
          anyOf:
            - type: string
            - type: 'null'
          title: Label
          description: >-
            Answer option to show the user. Send this value back as the answer
            for a `select` question.
          example: Get the first 100 users
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: >-
            Short clarification of what this option means, or `null` if none was
            generated.
          example: Focus on early adopters who give feedback
      type: object
      title: ViralityQuestionOption
    ContentStrategy:
      properties:
        app_summary:
          anyOf:
            - type: string
            - type: 'null'
          title: App Summary
          description: Short summary of what the app does.
          example: A CRM for freelancers who want to track leads without a spreadsheet.
        marketing_approach:
          anyOf:
            - type: string
            - type: 'null'
          title: Marketing Approach
          description: >-
            The approach the content takes, extracted from the accepted
            strategy. Empty if the strategy text was empty when the plan was
            generated.
          example: Lead with the spreadsheet pain, then show the app solving it.
        platforms:
          items:
            $ref: '#/components/schemas/PlatformContentPlan'
          type: array
          title: Platforms
          description: One entry per platform you approved, in the order you sent them.
      type: object
      title: ContentStrategy
    TeaserStatus:
      type: string
      enum:
        - generating
        - ready
        - failed
      title: TeaserStatus
    SocialPost:
      properties:
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
          description: >-
            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).
          example: 3f2504e0-4f89-11d3-9a0c-0305e82c3301
        platform:
          anyOf:
            - $ref: '#/components/schemas/Platform'
            - type: 'null'
          description: Platform the post is written for.
          example: instagram
        angle:
          anyOf:
            - $ref: '#/components/schemas/PostAngle'
            - type: 'null'
          description: Editorial angle the post takes.
          example: pain_point
        angle_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Angle Label
          description: Human-readable label for the angle.
          example: Pain point
        post_number:
          anyOf:
            - type: integer
            - type: 'null'
          title: Post Number
          description: Position of this post within its platform's set, starting at 1.
          example: 1
        total_posts:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Posts
          description: Number of posts generated for this platform.
          example: 5
        suggested_day:
          anyOf:
            - type: integer
            - type: 'null'
          title: Suggested Day
          description: Suggested day to publish on, counted from the start of the campaign.
          example: 1
        rationale:
          anyOf:
            - type: string
            - type: 'null'
          title: Rationale
          description: Why this post works for this platform and angle.
          example: Opens on the spreadsheet frustration the audience already has.
        content:
          anyOf:
            - type: string
            - type: 'null'
          title: Content
          description: >-
            The post text, ready to publish. Change it with [Update post
            content](/api-reference/update-post-content).
          example: >-
            Still tracking leads in a spreadsheet? I built the thing I wanted
            instead.
        image_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Image Url
          description: >-
            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).
          example: https://storage.base44.com/virality/3f2504e0.png
        image_prompt:
          anyOf:
            - type: string
            - type: 'null'
          title: Image Prompt
          description: >-
            Prompt used to generate the post image, or `null` if the post has
            none.
          example: A freelancer closing a laptop at a tidy desk, warm morning light
        hashtags:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Hashtags
          description: Suggested hashtags, without the leading `#`.
          example:
            - freelance
            - buildinpublic
        post_title:
          anyOf:
            - type: string
            - type: 'null'
          title: Post Title
          description: >-
            Title for platforms that use one, such as Reddit and LinkedIn.
            `null` elsewhere.
          example: I built a CRM because spreadsheets kept losing my leads
        suggested_subreddits:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Suggested Subreddits
          description: Subreddits to consider for a Reddit post. Empty for other platforms.
          example:
            - r/freelance
            - r/SideProject
        launch_comment:
          anyOf:
            - type: string
            - type: 'null'
          title: Launch Comment
          description: >-
            First comment to post under the main post, or `null` if none was
            generated.
          example: Happy to answer questions about how it works.
        option_label:
          anyOf:
            - type: string
            - type: 'null'
          title: Option Label
          description: >-
            Label for this post when the platform's `mode` is `selection`, so
            you can tell the alternatives apart. `null` in `series` mode.
          example: Direct and personal
        best_for_context:
          anyOf:
            - type: string
            - type: 'null'
          title: Best For Context
          description: >-
            When to prefer this option over the others, or `null` if not
            applicable.
          example: Best if your audience already knows you
      type: object
      title: SocialPost
    PlatformContentPlan:
      properties:
        platform:
          anyOf:
            - $ref: '#/components/schemas/Platform'
            - type: 'null'
          description: Platform these posts are written for.
          example: instagram
        mode:
          anyOf:
            - $ref: '#/components/schemas/ContentMode'
            - type: 'null'
          description: >-
            How to read the posts. `series` is a sequence to publish in order,
            `selection` is a set of alternatives to pick one from.
          example: series
        reasoning:
          anyOf:
            - type: string
            - type: 'null'
          title: Reasoning
          description: Why the content for this platform takes the shape it does.
          example: Instagram rewards a consistent series, so these build on each other.
        posts:
          items:
            $ref: '#/components/schemas/SocialPost'
          type: array
          title: Posts
          description: The generated posts for this platform.
      type: object
      title: PlatformContentPlan
    Platform:
      type: string
      enum:
        - x
        - instagram
        - tiktok
        - linkedin
        - reddit
        - facebook
      title: Platform
    PostAngle:
      type: string
      enum:
        - pain_point
        - feature_demo
        - social_proof
        - trending_hook
        - user_story
        - before_after
      title: PostAngle
    ContentMode:
      type: string
      enum:
        - series
        - selection
      title: ContentMode
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: api_key
      description: Personal API key.

````