xpoz-ai

xpoz-ai Crawl Settings API

Tracked items collected on a schedule.

GitHub OpenAPI

Operations 6

GET /api/crawl/settings Get tracked items #
POST /api/crawl/settings Replace tracked items #
POST /api/crawl/settings/upload-csv Parse a tracked-items CSV #
GET /api/crawl/settings/export-csv Export tracked items as CSV #
POST /api/crawl/tweet Track a tweet #
GET /api/crawl/tweet List tracked tweets #

Specifications

⚙
OpenAPI
https://artifacts.apis.io/xpoz-ai/openapi/xpoz-ai-crawl-settings-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/xpoz-ai/json-schema/xpoz-ai-crawl-settings-schema.json
📊
JSONSchema
https://artifacts.apis.io/xpoz-ai/json-schema/xpoz-ai-operation-state-schema.json
📊
JSONSchema
https://artifacts.apis.io/xpoz-ai/json-schema/xpoz-ai-access-key-record-schema.json
📊
JSONSchema
https://artifacts.apis.io/xpoz-ai/json-schema/xpoz-ai-purchase-result-schema.json
📊
JSONSchema
https://artifacts.apis.io/xpoz-ai/json-schema/xpoz-ai-access-key-created-schema.json
📊
JSONSchema
https://artifacts.apis.io/xpoz-ai/json-schema/xpoz-ai-cursor-response-schema.json

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/xpoz-ai:xpoz-ai-crawl-settings-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

xpoz-ai-crawl-settings-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: XPOZ Crawl Settings 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: Crawl Settings
  description: Tracked items collected on a schedule.
paths:
  /api/crawl/settings:
    get:
      tags:
      - Crawl Settings
      summary: Get tracked items
      description: The caller's tracked keywords, users, subreddits, and hashtags per platform.
      security:
      - UserSession: []
      responses:
        '200':
          description: 'Tracked items, or `{success: true, data: null, message}` when none are configured.'
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/CrawlSettings'
                - type: object
                  properties:
                    success:
                      type: boolean
                      const: true
                    data:
                      type: 'null'
                    message:
                      type: string
        '401':
          $ref: '#/components/responses/UnauthorizedMessage'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyFailure'
      operationId: getCrawlSettings
    post:
      tags:
      - Crawl Settings
      summary: Replace tracked items
      description: Replace the caller's tracked items. Rejected when the plan limit is exceeded.
      security:
      - UserSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                items:
                  $ref: '#/components/schemas/CrawlSettings'
              required:
              - items
      responses:
        '200':
          description: Saved settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrawlSettingsRecord'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/UnauthorizedMessage'
        '403':
          description: Plan limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanLimitExceeded'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyFailure'
      operationId: postCrawlSettings
  /api/crawl/settings/upload-csv:
    post:
      tags:
      - Crawl Settings
      summary: Parse a tracked-items CSV
      description: Parse a CSV (`platform,type,value,country`) into tracked items without saving. Max 5 MiB. Requires the `uploadCrawlSettingsCsv` flag.
      security:
      - UserSession: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
              required:
              - file
      responses:
        '200':
          description: Parsed items.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    $ref: '#/components/schemas/CrawlSettings'
                required:
                - success
                - data
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/UnauthorizedMessage'
        '403':
          description: Missing flag or plan limit exceeded.
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ErrorField'
                - $ref: '#/components/schemas/PlanLimitExceeded'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyFailure'
      operationId: postCrawlSettingsUploadCsv
  /api/crawl/settings/export-csv:
    get:
      tags:
      - Crawl Settings
      summary: Export tracked items as CSV
      description: Download the caller's tracked items as `crawl-settings.csv`. Requires the `uploadCrawlSettingsCsv` flag.
      security:
      - UserSession: []
      responses:
        '200':
          description: CSV file.
          content:
            text/csv:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/UnauthorizedMessage'
        '403':
          $ref: '#/components/responses/NotAuthorized'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyFailure'
      operationId: getCrawlSettingsExportCsv
  /api/crawl/tweet:
    post:
      tags:
      - Crawl Settings
      summary: Track a tweet
      description: Start collecting engagement on a tweet for a number of days. Requires the `trackTweets` flag.
      security:
      - UserSession: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tweetId:
                  type: string
                  pattern: ^\d+$
                days:
                  type: integer
                  minimum: 1
                  maximum: 30
                  default: 7
              required:
              - tweetId
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetBuildCreated'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/UnauthorizedMessage'
        '403':
          $ref: '#/components/responses/NotAuthorized'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyFailure'
      operationId: postCrawlTweet
    get:
      tags:
      - Crawl Settings
      summary: List tracked tweets
      description: Tweet tracking requests of the caller. Requires the `trackTweets` flag.
      security:
      - UserSession: []
      responses:
        '200':
          description: Requests.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TweetCrawlRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedMessage'
        '403':
          $ref: '#/components/responses/NotAuthorized'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyFailure'
      operationId: getCrawlTweet
components:
  responses:
    ValidationError:
      description: Query or body validation failed. `message` joins all validation issues with `, `.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SimpleError'
    NotAuthorized:
      description: Caller lacks the required admin feature flag or `@xpoz.ai` email.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorField'
    UnauthorizedMessage:
      description: Missing or invalid credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MessageError'
  schemas:
    SimpleError:
      type: object
      properties:
        success:
          type: boolean
          const: false
        message:
          type: string
      required:
      - success
      - message
    PlanLimitExceeded:
      type: object
      properties:
        success:
          type: boolean
          const: false
        error:
          type: string
          enum:
          - PLAN_LIMIT_EXCEEDED
        message:
          type: string
        data:
          type: object
          properties:
            currentCount:
              type: integer
            planTrackedItems:
              type: integer
            extraTrackedItems:
              type: integer
            planName:
              type: string
      required:
      - success
      - error
      - message
    TweetCrawlRequest:
      type: object
      properties:
        id:
          type: string
        tweetId:
          type: string
        status:
          type: string
        endTime:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
        createdAt:
          type: string
          format: date-time
      required:
      - id
      - tweetId
      - status
      - createdAt
    CrawlSettings:
      type: object
      properties:
        twitter:
          type: object
          properties:
            keywords:
              type: array
              items:
                $ref: '#/components/schemas/TrackedKeyword'
            users:
              type: array
              items:
                type: string
        instagram:
          type: object
          properties:
            keywords:
              type: array
              items:
                $ref: '#/components/schemas/TrackedKeyword'
            users:
              type: array
              items:
                type: string
        reddit:
          type: object
          properties:
            keywords:
              type: array
              items:
                $ref: '#/components/schemas/TrackedKeyword'
            subreddits:
              type: array
              items:
                type: string
            users:
              type: array
              items:
                type: string
        tiktok:
          type: object
          properties:
            keywords:
              type: array
              items:
                $ref: '#/components/schemas/TrackedKeyword'
            users:
              type: array
              items:
                type: string
            hashtags:
              type: array
              items:
                type: string
      description: Tracked items per platform.
    CrawlSettingsRecord:
      type: object
      properties:
        id:
          type: string
        tenantId:
          type: string
        userEmail:
          type: string
        items:
          $ref: '#/components/schemas/CrawlSettings'
        frequencyMinutes:
          type: number
        lastCrawledAt:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
      required:
      - id
      - tenantId
      - userEmail
      - items
      - frequencyMinutes
      - createdAt
    LegacyFailure:
      type: object
      properties:
        success:
          type: boolean
          const: false
        message:
          type: string
        error:
          type: string
      required:
      - success
      - message
    ErrorField:
      type: object
      properties:
        error:
          type: string
      required:
      - error
    TrackedKeyword:
      anyOf:
      - type: string
      - type: object
        properties:
          value:
            type: string
          country:
            type: string
            pattern: ^[A-Za-z]{2}$
        required:
        - value
    DatasetBuildCreated:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
      required:
      - id
      - status
    MessageError:
      type: object
      properties:
        message:
          type: string
      required:
      - message
  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>`.'