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

# Stories Overview

> Create, retrieve, analyze, and delete time-limited image and video stories with the social.plus SDKs.

Stories are time-limited media items attached to a story target. The SDKs support image and video stories, optional metadata, optional hyperlink story items, live retrieval, view/link analytics, and soft or hard deletion.

The examples in this section use community targets, which are the common target shape across the SDKs covered here.

<Tip>
  For a product-level walkthrough, see [Stories & Ephemeral Content](/use-cases/social/stories-and-ephemeral-content). The pages in this SDK section stay focused on exact SDK methods and data shapes.
</Tip>

<CardGroup cols={3}>
  <Card title="Create" icon="plus">
    Publish image or video stories with optional metadata and hyperlink items.
  </Card>

  <Card title="Retrieve" icon="list">
    Observe individual stories, active story collections, story targets, and global story targets.
  </Card>

  <Card title="Analyze" icon="chart-bar">
    Mark stories as seen, mark hyperlink clicks, and query reached users where supported.
  </Card>
</CardGroup>

## Story Model

The exact accessor style differs by platform, but story objects expose the same main concepts:

| Field                                 | Description                                                                       |
| ------------------------------------- | --------------------------------------------------------------------------------- |
| `storyId`                             | Unique story identifier.                                                          |
| `targetType` / `targetId`             | Target that owns the story. The SDK examples use `community`.                     |
| `dataType`                            | Story content type, such as image or video.                                       |
| `data`                                | Media-specific story data, including image/video file references where available. |
| `items` / `storyItems`                | Interactive story items such as hyperlinks.                                       |
| `metadata`                            | Custom metadata provided during creation.                                         |
| `syncState` / `state`                 | Local creation state such as syncing, synced, or failed.                          |
| `isDeleted`                           | Whether the story is deleted.                                                     |
| `isSeen`                              | Whether the current user has seen the story.                                      |
| `impression`                          | Total view count exposed on the story model.                                      |
| `reach`                               | Unique reached-user count exposed on the story model.                             |
| `expiresAt`, `createdAt`, `updatedAt` | Story lifecycle timestamps.                                                       |

## Story Target Model

Story targets represent story availability for a target such as a community.

| Field                     | Description                                                  |
| ------------------------- | ------------------------------------------------------------ |
| `targetType` / `targetId` | Target identity.                                             |
| `hasUnseen`               | Whether the current user has unseen stories for this target. |
| `syncingStoriesCount`     | Local stories still syncing for this target.                 |
| `failedStoriesCount`      | Local stories that failed to sync for this target.           |
| `updatedAt`               | Last target update timestamp.                                |

## SDK Surface

| Workflow           | TypeScript                   | iOS                              | Android                              | Flutter                              |
| ------------------ | ---------------------------- | -------------------------------- | ------------------------------------ | ------------------------------------ |
| Create image       | `createImageStory()`         | `createImageStory(options:)`     | `createImageStory()`                 | `createImageStory()`                 |
| Create video       | `createVideoStory()`         | `createVideoStory(options:)`     | `createVideoStory()`                 | `createVideoStory()`                 |
| Single story       | `getStoryByStoryId()`        | `getStory(storyId:)`             | `getStory()`                         | `live.getStory()`                    |
| Active stories     | `getActiveStoriesByTarget()` | `getActiveStoriesByTarget(...)`  | `getActiveStories(...)`              | `getActiveStories(...).build()`      |
| Stories by targets | `getStoriesByTargetIds()`    | `getStoriesByTargets(...)`       | `getStoriesByTargets(...)`           | `getStoriesByTargets(...).build()`   |
| Story target       | `getTargetById()`            | `getStoryTarget(...)`            | `getStoryTarget(...)`                | `live.getStoryTaregt(...)`           |
| Story targets      | `getTargetsByTargetIds()`    | `getStoryTargets(...)`           | `getStoryTargets(...)`               | `getStoryTargets(...).build()`       |
| Global targets     | `getGlobalStoryTargets()`    | `getGlobalStoryTargets(option:)` | `getGlobalStoryTargets(...)`         | `GlobalStoryTargetLiveCollection`    |
| Analytics          | `story.analytics.*`          | `story.analytics.*`              | `storyRepository.analytics(story).*` | `storyRepository.analytics(story).*` |

<Note>
  Flutter's single story-target helper is currently named `getStoryTaregt` in the shipped SDK. The spelling above is intentional.
</Note>

## Accuracy Notes

* The SDK creation APIs accept image or video files and pass upload/processing errors through their platform-specific async pattern.
* File size, duration, and moderation limits are enforced by backend or network configuration. This SDK reference does not hardcode those values.
* Story analytics methods should be called on synced story objects. Native and Flutter SDKs explicitly no-op for unsynced stories.
* `SMART`, `UNSEEN`, `SEEN`, and `ALL` query options apply to global story target retrieval.

## Related Topics

<CardGroup cols={2}>
  <Card title="Create Story" href="./creation/create-story" icon="plus">
    Publish image and video stories.
  </Card>

  <Card title="Get Stories" href="./retrieval/get-stories" icon="list">
    Retrieve story live objects and collections.
  </Card>

  <Card title="Story Targets" href="./retrieval/get-story-targets" icon="bullseye-pointer">
    Retrieve target-level story availability and unseen status.
  </Card>

  <Card title="Story Impressions" href="./analytics/story-impressions" icon="chart-bar">
    Record story views, link clicks, and reached users.
  </Card>
</CardGroup>