> ## 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.

# Get Stories

> Retrieve individual stories, active stories for one target, or stories across multiple targets.

Story retrieval APIs return live objects or live collections. Use a single-story API when you already have a `storyId`, active-story APIs for a target's current stories, and multi-target APIs when building a story tray across communities.

## Parameters

| Operation                   | Parameter         | Required | Description                                                 |
| --------------------------- | ----------------- | -------- | ----------------------------------------------------------- |
| Single story                | `storyId`         | Yes      | Story ID to observe as a live object or stream.             |
| Active stories for a target | `targetType`      | Yes      | Story target type, such as community.                       |
| Active stories for a target | `targetId`        | Yes      | Target ID whose active stories should be retrieved.         |
| Active stories for a target | Sort/order option | No       | Sort order for returned active stories where exposed.       |
| Stories across targets      | `targets`         | Yes      | Target type and target ID pairs to retrieve in one request. |
| Stories across targets      | Sort/order option | No       | Sort order for returned stories where exposed.              |

## Single Story

Observe a single story when your UI already has a `storyId` and needs live story state.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { StoryRepository } from '@amityco/ts-sdk';

  const unsubscribe = StoryRepository.getStoryByStoryId(storyId, ({ data, loading, error }) => {
    if (error) {
      handleError(error);
      return;
    }

    if (!loading && data) {
      updateUI(data);
    }
  });

  unsubscribe();
  ```

  ```swift iOS theme={null}
  token = storyRepository.getStory(storyId: "story-id").observe { object, error in
      if let error {
          handleError(error)
          return
      }

      if let story = object.snapshot {
          showSuccessMessage(story.storyId)
      }
  }
  ```

  ```kotlin Android theme={null}
  fun observeStory(
      storyRepository: AmityStoryRepository,
      storyId: String
  ) {
      storyRepository.getStory(storyId = storyId)
          .doOnNext { story: AmityStory ->
              showSuccessMessage(story.getStoryId())
          }
          .doOnError { error -> showErrorMessage(error = error) }
          .subscribe()
  }
  ```

  ```dart Flutter theme={null}
  void observeStory(String storyId) {
    final stream = AmitySocialClient.newStoryRepository().live.getStory(storyId);

    stream.listen((story) {
      final currentStoryId = story.storyId;
      showError(currentStoryId ?? '');
    });
  }
  ```
</CodeGroup>

## Active Stories for a Target

Active-story APIs retrieve non-expired stories for one target. They are the usual choice for rendering a viewer after the user opens a story ring.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { StoryRepository } from '@amityco/ts-sdk';

  const unsubscribe = StoryRepository.getActiveStoriesByTarget(
    {
      targetType: 'community',
      targetId: communityId,
      options: {
        sortBy: 'createdAt',
        orderBy: 'desc',
      },
    },
    ({ data, loading, error }) => {
      if (error) {
        handleError(error);
        return;
      }

      if (!loading) {
        renderResults(data);
      }
    },
  );

  unsubscribe();
  ```

  ```swift iOS theme={null}
  token = storyRepository
      .getActiveStoriesByTarget(
          targetType: .community,
          targetId: communityId,
          sortOption: .lastCreated
      )
      .observe { collection, error in
          if let error {
              handleError(error)
              return
          }

          showSuccessMessage(collection.snapshots.count)
      }
  ```

  ```kotlin Android theme={null}
  fun observeActiveStories(
      storyRepository: AmityStoryRepository,
      targetId: String
  ) {
      storyRepository.getActiveStories(
          targetType = AmityStory.TargetType.COMMUNITY,
          targetId = targetId,
          sortOption = AmityStorySortOption.LAST_CREATED
      )
          .doOnNext { stories: PagingData<AmityStory> ->
              getPagingData(stories)
          }
          .doOnError { error -> showErrorMessage(error = error) }
          .subscribe()
  }
  ```

  ```dart Flutter theme={null}
  void observeActiveStories(String communityId) {
    final collection = StoryLiveCollection(
      request: () => AmitySocialClient.newStoryRepository()
          .getActiveStories(
            targetId: communityId,
            targetType: AmityStoryTargetType.COMMUNITY,
            orderBy: AmityStorySortingOrder.LAST_CREATED,
          )
          .build(),
    );

    collection.getStreamController().stream.listen((stories) {
      final visibleCount = stories.length;
      showError(visibleCount);
    });

    collection.getData();
  }
  ```
</CodeGroup>

## Stories Across Targets

Use the multi-target APIs when you need stories from multiple targets in one live collection.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { StoryRepository } from '@amityco/ts-sdk';

  const unsubscribe = StoryRepository.getStoriesByTargetIds(
    {
      targets: [
        { targetType: 'community', targetId: communityId },
        { targetType: 'community', targetId: 'community-id-2' },
      ],
      options: {
        sortBy: 'createdAt',
        orderBy: 'desc',
      },
    },
    ({ data, loading, error }) => {
      if (error) {
        handleError(error);
        return;
      }

      if (!loading) {
        renderResults(data);
      }
    },
  );

  unsubscribe();
  ```

  ```swift iOS theme={null}
  let targets = [
      AmityStoryTargetSearchInfo(targetType: .community, targetId: communityId),
      AmityStoryTargetSearchInfo(targetType: .community, targetId: "community-id-2")
  ]

  token = storyRepository
      .getStoriesByTargets(targets: targets, sortOption: .lastCreated)
      .observe { collection, error in
          if let error {
              handleError(error)
              return
          }

          showSuccessMessage(collection.snapshots.count)
      }
  ```

  ```kotlin Android theme={null}
  fun observeStoriesByTargets(storyRepository: AmityStoryRepository) {
      val targets = listOf(
          AmityStory.TargetType.COMMUNITY to "community-id-1",
          AmityStory.TargetType.COMMUNITY to "community-id-2"
      )

      storyRepository.getStoriesByTargets(
          targets = targets,
          sortOption = AmityStorySortOption.LAST_CREATED
      )
          .doOnNext { stories: List<AmityStory> ->
              showSuccessMessage(stories.size)
          }
          .doOnError { error -> showErrorMessage(error = error) }
          .subscribe()
  }
  ```

  ```dart Flutter theme={null}
  void observeStoriesByTargets() {
    final targets = [
      StoryTargetSearchInfo(
        targetType: AmityStoryTargetType.COMMUNITY,
        targetId: 'community-id-1',
      ),
      StoryTargetSearchInfo(
        targetType: AmityStoryTargetType.COMMUNITY,
        targetId: 'community-id-2',
      ),
    ];

    final collection = StoryLiveCollection(
      request: () => AmitySocialClient.newStoryRepository()
          .getStoriesByTargets(
            targets: targets,
            orderBy: AmityStorySortingOrder.LAST_CREATED,
          )
          .build(),
    );

    collection.getStreamController().stream.listen((stories) {
      final visibleCount = stories.length;
      showError(visibleCount);
    });

    collection.getData();
  }
  ```
</CodeGroup>

## Notes

* Active-story APIs include local optimistic stories where the platform SDK supports optimistic creation.
* Multi-target APIs return synced stories across the requested targets.
* Use story target APIs when you only need ring state such as `hasUnseen`.

## Related Topics

<CardGroup cols={2}>
  <Card title="Get Story Targets" href="./get-story-targets" icon="bullseye-pointer">
    Retrieve target-level story availability and unseen state.
  </Card>

  <Card title="Story Impressions" href="../analytics/story-impressions" icon="chart-bar">
    Track views and reached users for stories.
  </Card>
</CardGroup>