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

# List posts

> Retrieve social media posts with comprehensive filtering options.

Posts can be filtered by program, platform, creator, date range, and more.
Results include engagement metrics (views, likes, comments, etc.)

Agency accounts can pass `scope=agency` to list posts across the parent
agency and every subaccount in one call.




## OpenAPI

````yaml /openapi/platform-apikey.yaml get /posts
openapi: 3.0.4
info:
  title: Sideshift Public API
  version: 1.0.0
  description: >
    REST API for Sideshift platform. Authenticate using your API key in the
    `x-api-key` header.


    This document covers the **public, API-key-authenticated** surface. The

    restricted endpoints (Jobs, Applicants, payout execution/Quick Pay) are
    gated

    to an explicit partner allowlist and are documented in the **Full Access**

    spec (`sideshift-api-private.yaml`); a non-allowlisted key calling them

    receives `403`. API-key *management* (creating/rotating keys, digest

    automations) is performed in the dashboard with a Firebase session and is
    not

    part of this API-key contract.


    ## Requirements

    - **Active Subscription Required**: API access requires an active Sideshift
      subscription. Requests from a company without one return
      `402 { "error": "Active subscription required" }`.
    - API key from Settings → Integrations


    ## Rate Limits

    - Default: **100 requests per minute** per API key.

    - Allowlisted partner accounts: **400 requests per minute**.

    - Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and
      `X-RateLimit-Reset` headers; exceeding the limit returns `429`.

    ## Errors

    - Errors are returned as `{ "error": "<message>" }` with the appropriate
    HTTP
      status (`400` invalid request, `401` invalid/missing key, `402` no active
      subscription, `403` restricted endpoint / cross-company, `404` not found,
      `429` rate limited). Some endpoints add a `code` (e.g. `LEAD_NOT_FOUND`).

    ## Timestamps

    - All timestamps are Unix timestamps in milliseconds

    - Example: `1634567890000`


    ## Pagination

    - Most list endpoints support `page` (default: 1) and `limit` (default: 25,
      max: 100) parameters and return `{ data, page, total }`. Some additionally
      return `limit` and/or `totalPages`.
    - Agency (parent) accounts can pass `scope=agency` on analytics/posts
      endpoints to aggregate across the parent agency and every subaccount.

    ## Base URL

    - Production: `https://app.sideshift.app/api/v1`
servers:
  - url: https://app.sideshift.app/api/v1
    description: Production server
security:
  - apiKeyAuth: []
tags:
  - name: Programs
    description: Campaign and program management
  - name: Posts
    description: Social media posts and content
  - name: Analytics
    description: Performance metrics and KPIs
  - name: Payouts
    description: Payout management including pending payouts and execution
  - name: Contracts
    description: Creator contracts and agreements
  - name: Creators
    description: Creator profiles and statistics
  - name: Invoices
    description: Create, list, and send invoices to customers
  - name: Discover
    description: Read Discover leads (brand inquiries) submitted to your agency
paths:
  /posts:
    get:
      tags:
        - Posts
      summary: List posts
      description: >
        Retrieve social media posts with comprehensive filtering options.


        Posts can be filtered by program, platform, creator, date range, and
        more.

        Results include engagement metrics (views, likes, comments, etc.)


        Agency accounts can pass `scope=agency` to list posts across the parent

        agency and every subaccount in one call.
      parameters:
        - $ref: '#/components/parameters/ScopeParam'
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: limit
          schema:
            type: integer
            default: 25
            maximum: 100
        - in: query
          name: program
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
          description: Filter by program IDs (multiple allowed)
        - in: query
          name: platform
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
              enum:
                - tiktok
                - instagram
                - youtube
          description: Filter by platforms (multiple allowed)
        - in: query
          name: creator
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
          description: Filter by creator IDs (multiple allowed)
        - in: query
          name: fromDate
          schema:
            type: string
            format: date
          description: Filter posts from this date (YYYY-MM-DD)
        - in: query
          name: toDate
          schema:
            type: string
            format: date
          description: Filter posts until this date (YYYY-MM-DD)
      responses:
        '200':
          description: Successfully retrieved posts
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        title:
                          type: string
                        platform:
                          type: string
                        views:
                          type: integer
                        likes:
                          type: integer
                        comments:
                          type: integer
                        shares:
                          type: integer
                        earnings:
                          type: number
                        paid:
                          type: boolean
                        contractorName:
                          type: string
                        uploadedAt:
                          type: integer
                  page:
                    type: integer
                  total:
                    type: integer
components:
  parameters:
    ScopeParam:
      in: query
      name: scope
      required: false
      schema:
        type: string
        enum:
          - company
          - agency
        default: company
      description: |
        Data scope. `company` (default) returns only the authenticated
        company's own data. `agency` returns the union of the parent agency
        plus every subaccount — use this to pull analytics across all brands.

        `scope=agency` requires an API key belonging to a **parent agency**
        account (an account with `isAgency=true` and no parent). Passing it with
        a non-agency or subaccount key returns `403`.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication. Get yours from Settings → Integrations

````