xpoz-ai Operations API

openapi: 3.2.0
info:
  title: XPOZ Operations API
  version: 1.0.0
  description: 'Social media data API for Twitter/X, Instagram, Reddit, and TikTok.


    **Data endpoints** (`/api/data/*`) are authenticated with an API access key and are metered against the account''s credits. Most stored-data endpoints share the same query options: `fields` selects which attributes to return, `since`/`until` bound the date range, and `responseType` picks between a synchronous first page (`fast`), a full paged query run as a background operation (`paging`), and a CSV export (`csv`). `/live` endpoints fetch from the platform on demand and page with a cursor instead.


    **Account, billing, and crawl-settings endpoints** are used by the XPOZ dashboard and authenticate with the user''s session.'
servers:
- url: /
  description: This server
tags:
- name: Operations
  description: Polling for background operations started with `responseType=paging`.
paths:
  /api/data/operations/{id}:
    get:
      tags:
      - Operations
      summary: Get operation status
      description: Poll a background operation started by a `responseType=paging` request. Poll every few seconds until `status` is `success`, `no_data`, or `error`. Completed operations expire 15 minutes after finishing.
      security:
      - AccessKey: []
      parameters:
      - $ref: '#/components/parameters/OperationId'
      responses:
        '200':
          description: Operation state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationState'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Unknown or expired operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        default:
          $ref: '#/components/responses/DataRouteError'
      operationId: getDataOperationsId
components:
  responses:
    DataRouteError:
      description: The request could not be fulfilled. Status is 400 for an empty or invalid search query, 402 when CSV export is blocked by plan limits, 500 otherwise.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DataRouteError'
    Unauthorized:
      description: Missing or invalid credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SimpleError'
  schemas:
    SimpleError:
      type: object
      properties:
        success:
          type: boolean
          const: false
        message:
          type: string
      required:
      - success
      - message
    DataResponse:
      type: object
      properties:
        results:
          type: array
          items:
            type: object
            additionalProperties: true
            description: Entity shaped by the requested `fields`.
        count:
          type: integer
        dataSource:
          $ref: '#/components/schemas/DataSource'
        pagination:
          $ref: '#/components/schemas/Pagination'
        export:
          $ref: '#/components/schemas/ExportInfo'
        dbQuery:
          type: string
      required:
      - results
      - count
      - dataSource
      description: Standard envelope for stored-data endpoints. `pagination` is present on paged results, `export` when a CSV export was queued, and `dbQuery` echoes the executed query. When nothing matched, `results` is empty and `count` is 0.
    ExportInfo:
      type: object
      properties:
        dataDumpExportOperationId:
          type: string
      required:
      - dataDumpExportOperationId
    DataRouteError:
      type: object
      properties:
        success:
          type: boolean
          const: false
        message:
          type: string
          description: Endpoint-specific label, e.g. `Failed to retrieve Twitter posts`.
        error:
          type: string
          description: Detail. `An unexpected error occurred` for unhandled failures.
      required:
      - success
      - message
      - error
    OperationState:
      type: object
      properties:
        operationId:
          type: string
        status:
          type: string
          enum:
          - running
          - success
          - error
          - no_data
          - cancelled
        result:
          description: Present once the operation finished successfully. Holds the same envelope the synchronous endpoint would have returned.
          anyOf:
          - $ref: '#/components/schemas/DataResponse'
          - $ref: '#/components/schemas/RedditPostWithComments'
          - $ref: '#/components/schemas/RedditSubredditWithPosts'
        error:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
      - operationId
      - status
      - createdAt
      - updatedAt
    RedditSubredditWithPosts:
      type: object
      properties:
        subreddit:
          type: object
          additionalProperties: true
          description: Entity shaped by the requested `fields`.
        results:
          type: array
          items:
            type: object
            additionalProperties: true
            description: Entity shaped by the requested `fields`.
        count:
          type: integer
        dataSource:
          $ref: '#/components/schemas/DataSource'
        pagination:
          $ref: '#/components/schemas/Pagination'
        dbQuery:
          type: string
      required:
      - subreddit
      - results
      - count
      - dataSource
      description: A subreddit plus a page of its posts.
    Pagination:
      type: object
      properties:
        totalRows:
          type: integer
        totalPages:
          type: integer
        resultsCount:
          type: integer
        pageSize:
          type: integer
        tableName:
          type: string
      required:
      - resultsCount
      - pageSize
      - tableName
    DataSource:
      type: string
      enum:
      - database
      - api
      - hybrid
      description: Where the results came from.
    RedditPostWithComments:
      type: object
      properties:
        post:
          type: object
          additionalProperties: true
          description: Entity shaped by the requested `fields`.
        results:
          type: array
          items:
            type: object
            additionalProperties: true
            description: Entity shaped by the requested `fields`.
        count:
          type: integer
        dataSource:
          $ref: '#/components/schemas/DataSource'
        pagination:
          $ref: '#/components/schemas/Pagination'
        dbQuery:
          type: string
      required:
      - post
      - results
      - count
      - dataSource
      description: A Reddit post plus a page of its comments.
  parameters:
    OperationId:
      name: id
      in: path
      required: true
      description: Operation ID returned by a `responseType=paging` request, e.g. `op_2f1c...`.
      schema:
        type: string
  securitySchemes:
    AccessKey:
      type: http
      scheme: bearer
      description: 'XPOZ API access key, created from the dashboard or `POST /api/tokens`. Send as `Authorization: Bearer <access key>`.'
    UserSession:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Descope session JWT of a logged-in dashboard user. Send as `Authorization: Bearer <session JWT>`.'