socialdata-tools Monitoring API

openapi: 3.2.0
info:
  title: SocialData API Reference Monitoring API
  description: SocialData API is a scalable and reliable API that simplifies the process of fetching data from Twitter/X. With SocialData API, you can easily retrieve tweets, user profiles, user followers/following and other information without the need for proxies or parsing Twitter responses.
  termsOfService: https://socialdata.tools/legal/terms-and-conditions
  contact:
    email: support@socialdata.tools
  version: 1.0.0
servers:
- url: https://api.socialdata.tools
security:
- bearerAuth: []
tags:
- name: Monitoring API
  description: Endpoints for creating and managing your monitors
paths:
  /user/webhook:
    post:
      tags:
      - Monitoring API
      summary: Set Global Webhook URL
      description: Used to set webhook URL that will be used for all monitors that don't have a monitor-specific webhook_url set.
      operationId: setGlobalWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type:
                  - string
                  - 'null'
                  description: New webhook URL that will be used for all monitors that don't have an individual webhook_url set
                  format: uri
              required:
              - url
            example:
              url: https://my-website.com/webhook
      responses:
        '200':
          description: Webhook URL successfully set
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: Webhook URL updated
        '422':
          description: Validation failed (e.g. invalid URL format)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: API internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      externalDocs:
        url: https://docs.socialdata.tools/monitoring/set-global-webhook-url/
  /user/webhook/secret:
    post:
      tags:
      - Monitoring API
      summary: Set Webhook Secret
      description: Sets the shared secret used to sign every webhook we send you. Your server uses the same value to confirm a request is authentic. You choose the value; there is no generate-a-secret endpoint. Calling this endpoint again replaces the previous secret. The account has one secret, shared by every monitor and every webhook URL. There is no endpoint that returns the current secret - it can only be overwritten.
      operationId: setWebhookSecret
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                secret:
                  type: string
                  maxLength: 256
                  description: The shared secret used to sign webhook requests. Maximum 256 characters. Store it somewhere your webhook handler can read it, and treat it like a password.
              required:
              - secret
            example:
              secret: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
      responses:
        '200':
          description: Webhook secret successfully set
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: Webhook secret updated
        '422':
          description: Validation failed (e.g. the secret field was not provided)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
      externalDocs:
        url: https://docs.socialdata.tools/monitoring/set-webhook-secret/
  /monitors/user-tweets:
    post:
      tags:
      - Monitoring API
      summary: Create New User Tweets Monitor
      description: Creates a new monitor to receive alerts when the target Twitter user posts a new tweet or makes a retweet. When adding a new monitor SocialData will attempt to fetch user details and return HTTP Status 422 in case the user timeline is protected or user not found.
      operationId: createUserTweetsMonitor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                  description: User ID of the target user. Required if user_screen_name not provided.
                  example: 1493446837214187523
                user_screen_name:
                  type: string
                  description: Username of the target user without @. Required if user_id not provided.
                  example: elonmusk
                webhook_url:
                  type: string
                  format: uri
                  description: Monitor-specific webhook URL that will override your global webhook URL. Not required.
                  example: https://my-website.com/webhook
              oneOf:
              - required:
                - user_id
              - required:
                - user_screen_name
            examples:
              withUserId:
                value:
                  user_id: '1493446837214187523'
                  webhook_url: https://my-website.com/webhook
              withScreenName:
                value:
                  user_screen_name: elonmusk
                  webhook_url: https://my-website.com/webhook
      responses:
        '200':
          description: Monitor created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    $ref: '#/components/schemas/Monitor'
        '402':
          description: Payment required - not enough credits to perform this request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation failed (e.g. user not found or timeline is protected)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: API internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      externalDocs:
        url: https://docs.socialdata.tools/monitoring/create-user-tweets-monitor/
  /monitors/user-following:
    post:
      tags:
      - Monitoring API
      summary: Create Twitter User Following Monitor
      description: Creates a new monitor to receive alerts when the target Twitter user follows someone.
      operationId: createUserFollowingMonitor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                  description: User ID of the target user. Required if user_screen_name not provided.
                  example: 1493446837214187523
                user_screen_name:
                  type: string
                  description: Username of the target user without @. Required if user_id not provided.
                  example: elonmusk
                webhook_url:
                  type: string
                  format: uri
                  description: Monitor-specific webhook URL that will override your global webhook URL. Not required.
                  example: https://my-website.com/webhook
              oneOf:
              - required:
                - user_id
              - required:
                - user_screen_name
            examples:
              withUserId:
                value:
                  user_id: 1493446837214187523
                  webhook_url: https://my-website.com/webhook
              withScreenName:
                value:
                  user_screen_name: elonmusk
                  webhook_url: https://my-website.com/webhook
      responses:
        '200':
          description: Monitor created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    $ref: '#/components/schemas/Monitor'
        '402':
          description: Payment required - not enough credits to perform this request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation failed (e.g. user not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: API internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      externalDocs:
        url: https://docs.socialdata.tools/monitoring/create-user-following-monitor/
  /monitors/user-profile:
    post:
      tags:
      - Monitoring API
      summary: Create Twitter User Profile Monitor
      description: 'Creates a new monitor to receive alerts when the target Twitter user changes their profile. Changes in any of the following user profile properties will trigger an event: name, screen_name, location, url, description, profile_banner_url, profile_image_url_https'
      operationId: createUserProfileMonitor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                  description: User ID of the target user. Required if user_screen_name not provided.
                  example: 1493446837214187523
                user_screen_name:
                  type: string
                  description: Username of the target user without @. Required if user_id not provided.
                  example: elonmusk
                webhook_url:
                  type: string
                  format: uri
                  description: Monitor-specific webhook URL that will override your global webhook URL. Not required.
                  example: https://my-website.com/webhook
              oneOf:
              - required:
                - user_id
              - required:
                - user_screen_name
            examples:
              withUserId:
                value:
                  user_id: 1493446837214187523
                  webhook_url: https://my-website.com/webhook
              withScreenName:
                value:
                  user_screen_name: elonmusk
                  webhook_url: https://my-website.com/webhook
      responses:
        '200':
          description: Monitor created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    $ref: '#/components/schemas/Monitor'
        '402':
          description: Payment required - not enough credits to perform this request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation failed (e.g. user not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: API internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      externalDocs:
        url: https://docs.socialdata.tools/monitoring/create-user-profile-monitor/
  /monitors/search-query:
    post:
      tags:
      - Monitoring API
      summary: Create New Search Query Monitor
      description: 'Creates a new search query monitor. SocialData will run your monitor every refresh_frequency seconds, retrieve recent search results for query, and dispatch each new matching tweet as an individual webhook event.


        The first execution delivers nothing - it records which tweets already match your query so that only genuinely new ones are reported afterwards. Each tweet is delivered once. Tweets that are already old when found are skipped; the cutoff is twice your refresh_frequency, or 10 minutes, whichever is longer.


        Search monitors are billed per delivered tweet and also for each execution that delivers nothing, so refresh_frequency sets your floor cost.'
      operationId: createSearchQueryMonitor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  maxLength: 512
                  description: A UTF-8, URL-encoded search query of up to 512 characters, including any operators supported by Twitter's website search
                  example: from:elonmusk doge
                refresh_frequency:
                  type: integer
                  minimum: 1
                  maximum: 3600
                  default: 30
                  description: How often the monitor executes, in seconds. This is the main driver of what the monitor costs.
                  example: 300
                webhook_url:
                  type: string
                  format: uri
                  description: Monitor-specific webhook URL that will override your global webhook URL. Not required.
                  example: https://my-website.com/webhook
              required:
              - query
            example:
              query: from:elonmusk doge
              refresh_frequency: 300
              webhook_url: https://my-website.com/webhook
      responses:
        '200':
          description: Monitor created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    $ref: '#/components/schemas/Monitor'
        '402':
          description: Payment required - not enough credits to perform this request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation failed (e.g. query was not provided or refresh_frequency is out of range)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      externalDocs:
        url: https://docs.socialdata.tools/monitoring/create-search-query-monitor/
  /monitors:
    get:
      tags:
      - Monitoring API
      summary: List Active Monitors
      description: Returns a list of monitors owned by the user.
      operationId: listMonitors
      parameters:
      - name: page
        in: query
        required: false
        description: Page number.
        schema:
          type: integer
          minimum: 1
          default: 1
        example: 2
      - name: per_page
        in: query
        required: false
        description: Monitors returned per page. Values above 50 are capped at 50.
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 25
        example: 50
      responses:
        '200':
          description: List of active monitors retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Monitor'
                  meta:
                    type: object
                    properties:
                      page:
                        type: integer
                        description: Current page number
                        example: 1
                      last_page:
                        type: integer
                        description: Total number of pages
                        example: 2
                      items_count:
                        type: integer
                        description: Total number of monitors
                        example: 100
                required:
                - data
                - meta
              example:
                data:
                - id: 01jhfkd7xsvy6afdmwycs1qn61
                  created_at: '2025-01-13T15:30:02.000000Z'
                  monitor_type: user_following
                  status: active
                  webhook_url: null
                  parameters:
                    user_screen_name: elonmusk
                    user_name: Elon Musk
                    user_id_str: '44196397'
                - id: 01jhfkdcmt0d8fjbbxqrtqbmck
                  created_at: '2025-01-13T15:30:07.000000Z'
                  monitor_type: user_tweets
                  status: paused
                  webhook_url: null
                  parameters:
                    user_screen_name: elonmusk
                    user_name: Elon Musk
                    user_id_str: '44196397'
                - id: 01jqty3m3dhg9xpsj373x12ck7
                  created_at: '2025-01-13T15:31:22.000000Z'
                  monitor_type: search_keyword
                  status: active
                  webhook_url: https://my-website.com/webhook
                  parameters:
                    query: from:elonmusk doge
                  refresh_frequency: 300
                meta:
                  page: 1
                  last_page: 2
                  items_count: 100
        '500':
          description: API internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      externalDocs:
        url: https://docs.socialdata.tools/monitoring/list-active-monitors/
  /monitors/{monitor_id}:
    get:
      tags:
      - Monitoring API
      summary: Get Monitor Details
      description: Returns details about a specific monitor.
      operationId: getMonitorDetails
      parameters:
      - name: monitor_id
        in: path
        required: true
        description: Target monitor ID.
        schema:
          type: string
        example: 01jeg76qa91b095gttamsbwa6q
      responses:
        '200':
          description: Request succeeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    $ref: '#/components/schemas/Monitor'
        '404':
          description: Monitor not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: API internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      externalDocs:
        url: https://docs.socialdata.tools/monitoring/get-monitor-details/
    patch:
      tags:
      - Monitoring API
      summary: Edit Monitor Settings
      description: Updates a single monitor's settings. You can change its webhook_url and, for search monitors, its refresh_frequency. Updating webhook_url only affects this one monitor and does not change your global webhook URL. When a monitor-specific webhook is not set, all webhook requests will be routed to your global webhook URL.
      operationId: editMonitorWebhook
      parameters:
      - name: monitor_id
        in: path
        required: true
        description: Target monitor ID.
        schema:
          type: string
        example: 01jeg76qa91b095gttamsbwa6q
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                webhook_url:
                  type:
                  - string
                  - 'null'
                  format: uri
                  description: New webhook URL for this monitor. Pass null to remove the monitor-specific webhook and fall back to your global webhook URL.
                refresh_frequency:
                  type: integer
                  minimum: 1
                  maximum: 3600
                  description: Search monitors only. How often the monitor executes, in seconds. Sending this for any other monitor type returns a validation error. The new frequency takes effect from the monitor's next execution.
                  example: 300
            examples:
              setWebhook:
                value:
                  webhook_url: https://my-website.com/webhook
              removeWebhook:
                value:
                  webhook_url: null
              setRefreshFrequency:
                value:
                  refresh_frequency: 300
      responses:
        '200':
          description: Webhook URL successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    $ref: '#/components/schemas/Monitor'
        '404':
          description: Monitor not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation failed (e.g. invalid URL format)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: API internal error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      externalDocs:
        url: https://docs.socialdata.tools/monitoring/edit-monitor-webhook/
    delete:
      tags:
      - Monitoring API
      summary: Delete Monitor
      description: Deletes an active monitor. This action stops the API from monitoring new events for the target user profile and halts all future charges associated with this monitor.
      operationId: deleteMonitor
      parameters:
      - name: monitor_id
        in: path
        required: true
        description: Target monitor ID.
        schema:
          type: string
        example: 01jeg76qa91b095gttamsbwa6q
      responses:
        '200':
          description: Monitor successfully deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '404':
          description: Monitor not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: API internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      externalDocs:
        url: https://docs.socialdata.tools/monitoring/delete-monitor/
  /monitors/{monitor_id}/events:
    get:
      tags:
      - Monitoring API
      summary: List Monitor Events
      description: Returns the delivery history for a monitor - one entry per webhook request we made, newest first. Use it to find deliveries your server rejected or never received. Reading history costs nothing; these events were already billed when they were detected.
      operationId: listMonitorEvents
      parameters:
      - name: monitor_id
        in: path
        required: true
        description: Target monitor ID.
        schema:
          type: string
        example: 01jeg76qa91b095gttamsbwa6q
      responses:
        '200':
          description: Request succeeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/MonitorEvent'
                required:
                - data
        '404':
          description: Not found - requested monitor does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      externalDocs:
        url: https://docs.socialdata.tools/monitoring/monitor-event-history/
  /monitors/{monitor_id}/events/{event_id}:
    get:
      tags:
      - Monitoring API
      summary: Get Monitor Event Details
      description: Returns a single event, including the full webhook payload we sent and the body your server responded with. The request_body value contains the exact JSON we posted to your webhook URL, so you can parse it to replay the event as if it had been delivered normally.
      operationId: getMonitorEventDetails
      parameters:
      - name: monitor_id
        in: path
        required: true
        description: Target monitor ID.
        schema:
          type: string
        example: 01jeg76qa91b095gttamsbwa6q
      - name: event_id
        in: path
        required: true
        description: Event ID, as returned in the id field by the list monitor events endpoint.
        schema:
          type: string
        example: MTAwMDAwMDk4NzY1NDMyMQ==
      responses:
        '200':
          description: Request succeeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/MonitorEventDetails'
                required:
                - data
        '404':
          description: Not found - requested monitor or event does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      externalDocs:
        url: https://docs.socialdata.tools/monitoring/monitor-event-history/
components:
  schemas:
    ValidationErrorResponse:
      type: object
      description: Laravel-style validation error, returned by endpoints that validate individual fields
      properties:
        message:
          type: string
          example: The secret field is required.
        errors:
          type: object
          description: One entry per rejected field, each holding an array of messages
          additionalProperties:
            type: array
            items:
              type: string
          example:
            secret:
            - The secret field is required.
      required:
      - message
      - errors
    Monitor:
      type: object
      description: Represents a monitor configuration
      properties:
        id:
          type: string
          description: Unique identifier for the monitor
          example: 01jhfkd7xsvy6afdmwycs1qn61
        created_at:
          type: string
          format: date-time
          description: The UTC datetime when the monitor was created
          example: '2025-01-13T15:30:02.000000Z'
        monitor_type:
          type: string
          enum:
          - user_tweets
          - user_following
          - user_profile
          - search_keyword
          description: Type of monitor
          example: user_tweets
        status:
          type: string
          enum:
          - active
          - paused
          description: Whether the monitor is currently checking for updates. A monitor is paused when a charge could not be collected from your balance, and resumes automatically once you top up.
          example: active
        refresh_frequency:
          type: integer
          minimum: 1
          maximum: 3600
          description: Search monitors only. How often the monitor executes, in seconds.
          example: 300
        webhook_url:
          type:
          - string
          - 'null'
          format: uri
          description: Monitor-specific webhook URL that overrides the global webhook URL, if set
          example: null
        parameters:
          type: object
          description: Configuration parameters specific to the type of monitor
      required:
      - id
      - created_at
      - monitor_type
      - status
      - parameters
    MonitorEvent:
      type: object
      description: One webhook delivery attempt made by a monitor
      properties:
        id:
          type: string
          description: Event ID, used to fetch the event details
          example: MTAwMDAwMDk4NzY1NDMyMQ==
        created_at:
          type: string
          format: date-time
          description: The UTC datetime when the delivery was attempted
          example: '2026-08-01T14:22:31.000000Z'
        url:
          type: string
          format: uri
          description: The webhook URL the request was sent to
          example: https://my-website.com/webhook
        response_code:
          type:
          - integer
          - 'null'
          description: The HTTP status your server returned. A null value means the request never completed - a timeout, a DNS failure, or a connection that was refused.
          example: 200
      required:
      - id
      - created_at
      - url
      - response_code
    MonitorEventDetails:
      allOf:
      - $ref: '#/components/schemas/MonitorEvent'
      - type: object
        properties:
          request_body:
            type: string
            description: The exact JSON we posted to your webhook URL. Parse it to replay the event as if it had been delivered normally.
          response_body:
            type:
            - string
            - 'null'
            description: The body your server responded with
        required:
        - request_body
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - error
        message:
          type: string
      required:
      - status
      - message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'Each request to SocialData API needs to contain your API key in the Authorization header.

        Example: `Authorization: Bearer YOUR_API_KEY`'
externalDocs:
  description: SocialData API Reference
  url: https://docs.socialdata.tools