Skip to main content
The social.plus SDK provides powerful post querying functionality that enables flexible content discovery and filtering. Query posts from communities, user feeds, or across the entire platform with customizable search criteria and real-time results.

Live Collection

Query results are returned as live collections with real-time updates

Flexible Filtering

Filter by post type, target, deletion status, and custom criteria

​
Query Parameters

ParameterTypeRequiredDescription
targetIdString✅ID of the community or user respectively. Use community ID for community posts or user ID for user feed posts.
targetTypeEnum✅Type of the target, either a particular community (community) or a user feed (user).
typesArray❌Available post types: video, image, file, liveStream, poll, and custom. If not specified, returns all post types for the target.
tagsArray❌Filter posts by specific tags. When specified, only posts containing these tags will be returned. Useful for content categorization and topic-based filtering.
includeDeletedBoolean❌Deletion filter. When true, retrieves both deleted and non-deleted posts. When false (default), only non-deleted posts are returned. Excludes all deleted posts (both soft and hard deleted) not owned by the logged-in user. Community moderators can see soft-deleted posts in community feeds, while users can see their own soft-deleted posts in their user feeds.
sortByEnum❌Sort order for results. lastCreated (default) shows most recently created posts first, firstCreated shows earliest created posts first.
feedTypeEnum❌Type of the feed filter. Possible values: published, reviewing, declined. See Feed Types for details.
includeMixedStructureBoolean❌Mixed media filter. When true, posts with mixed media (combining multiple media types) are included in results when filtering by types. When false (default), only posts with pure single-type structures are returned. See Mixed Media Filtering for details.
untilAtDateTime❌Time boundary for pagination (local-only). Stops fetching and collecting posts beyond this datetime. The comparison is exclusive. Available on iOS and Android only. See Time-Bounded Pagination.

​
Feed Types

Value: publishedPosts that have been approved and are visible to community members. This is the default state for most posts in communities without review requirements.
Value: reviewingPosts that are pending moderator approval. These posts are only visible to the post author and community moderators until approved.
Value: declinedPosts that have been rejected by moderators. These posts are only visible to the post author and community moderators.

​
Mixed Media Filtering

The includeMixedStructure parameter controls whether posts with mixed media types are included when filtering by specific post types. This is particularly useful when querying for content galleries or type-specific feeds.
Posts can have different structure types based on their attachments:
  • Pure Structure: Posts with a single media type (e.g., only images, only videos, only audio files)
  • Mixed Structure: Posts combining multiple media types (e.g., images + videos, audio + files, any combination)
When includeMixedStructure = false (default), querying for specific types returns only posts with pure single-type structures:
// Query for images only
const options = {
  targetId: "community-123",
  targetType: "community",
  types: ["image"],
  includeMixedStructure: false  // or omit (default)
};

// Returns:
// ✅ Posts with ONLY images (structureType: 'image')
// ❌ Posts with images + videos (structureType: 'mixed')
// ❌ Posts with images + audio (structureType: 'mixed')
This is ideal for:
  • Pure photo galleries
  • Type-specific content feeds
  • Simplified content categorization
Learn more about post structure types and creating mixed media posts in the Mixed Media Posts guide.
var token: AmityNotificationToken?

func postQueryExample() {
    // In this example, we will query posts to build user's media gallery.
    // This gallery shows the feed; specifically "image" and "video".
    //
    // 1. Create AmityPostQueryOptions
    // For this use-case:
    // - Search all the "image" and "video" posts
    // - Belong to a user, for example "steven".
    // - Only non-deleted posts.
    // - Sorted by last created.
    let options = AmityPostQueryOptions(
        targetType: .user,
        targetId: "steven",
        sortBy: .lastCreated,
        deletedOption: .notDeleted,
        dataTypes: ["image", "video"]
    )
    // 2. query the posts, and handle the results via the live collection.
    token = postRepository.getPosts(options).observe { collection, changes, error in
        // Observe the live collection changes here.
    }
}

func queryPostsWithTags() {
    // Query posts filtered by tags for topic-based content discovery.
    // Maximum 5 tags can be specified.
    let options = AmityPostQueryOptions(
        targetType: .community,
        targetId: "<community-id>",
        sortBy: .lastCreated,
        deletedOption: .notDeleted,
        dataTypes: nil,
        feedType: .published,
        tags: ["product", "promotion"]
    )

    token = postRepository.getPosts(options).observe { collection, changes, error in
        // Observe the live collection changes here.
    }
}

​
Parameter Usage Examples

Use Case: Display a user’s complete post history including their own deleted posts
const options = {
  targetId: "user-456",
  targetType: "user",
  // types not specified = all post types
  includeDeleted: true, // Shows user's own soft-deleted posts
  sortBy: "firstCreated"
};
This query shows all post types from the user’s timeline, including their own soft-deleted posts, sorted from oldest to newest.
Use Case: Community moderators reviewing pending posts
const options = {
  targetId: "community-789",
  targetType: "community",
  feedType: "reviewing",
  includeDeleted: false,
  sortBy: "lastCreated"
};
This query retrieves only posts that are pending review in the community, helping moderators efficiently process approval queues.
Use Case: Find posts with specific tags for topic-based content filtering
const options = {
  targetId: "community-101",
  targetType: "community",
  tags: ["tutorial", "beginner", "javascript"],
  feedType: "published",
  sortBy: "lastCreated"
};
This query filters for posts tagged with “tutorial”, “beginner”, and “javascript”, perfect for creating topic-specific feeds or educational content discovery.
Use Case: Combine tags with content type filtering for specialized searches
const options = {
  targetId: "community-202",
  targetType: "community",
  types: ["video", "image"],
  tags: ["product-demo", "feature-announcement"],
  feedType: "published",
  sortBy: "lastCreated"
};
This query finds visual content (videos and images) tagged with product or feature-related tags, ideal for creating marketing galleries or product showcase feeds.
Use Case: Access declined posts for audit or appeal purposes
const options = {
  targetId: "community-202",
  targetType: "community",
  feedType: "declined",
  includeDeleted: true,
  sortBy: "firstCreated"
};
This query retrieves declined posts including deleted ones, sorted chronologically for audit trail purposes. Only available to moderators and administrators.

​
Time-Bounded Pagination with untilAt

Platform Availability: The untilAt parameter is currently available on iOS and Android only. Web (TypeScript) support is under development.
The untilAt parameter enables time-bounded pagination for post queries (including community feed queries via targetType: 'community'). When provided, the SDK stops fetching and collecting posts beyond the specified datetime boundary.
  • Automatic pagination stop — Once the boundary is reached, no further pages are fetched and hasNextPage becomes false.
  • Real-time filtering — New posts arriving via real-time events are also checked against the boundary.
Sort DirectionuntilAt Acts AsExcludes Posts Where
lastCreated (newest first)Lower boundcreatedAt < untilAt (older than boundary)
firstCreated (oldest first)Upper boundcreatedAt > untilAt (newer than boundary)
// Query community posts from the last 7 days only
let oneWeekAgo = Calendar.current.date(byAdding: .day, value: -7, to: Date())!

let options = AmityPostQueryOptions(
    targetType: .community,
    targetId: "community-123",
    sortBy: .lastCreated,
    deletedOption: .notDeleted,
    untilAt: oneWeekAgo
)

token = postRepository.getPosts(options).observe { collection, changes, error in
    // All posts will have createdAt >= oneWeekAgo
}
Limitations: untilAt does not affect posts already persisted in the local database — it only controls what appears in the live collection result. When not provided, pagination behaves normally with no time boundary.

​
Common Use Cases

Community Feed

Display all posts in a community with real-time updates and customizable filtering options.

User Profile

Show a user’s post history with privacy controls and content type filtering.

Media Gallery

Create image and video galleries by filtering posts with media attachments.

​
Best Practices

  • Use specific post types instead of querying all types
  • Implement pagination for large result sets
  • Cache frequently accessed queries
  • Dispose of live collections when no longer needed
  • Show loading states during query execution
  • Implement pull-to-refresh for live collections
  • Provide empty states for no results
  • Use skeleton screens for better perceived performance
  • Handle network connectivity issues gracefully
  • Implement retry mechanisms for failed queries
  • Provide meaningful error messages to users
  • Log query errors for debugging purposes
  • Dispose of live collections when views are destroyed
  • Implement proper lifecycle management
  • Use weak references to prevent memory leaks
  • Monitor memory usage in production