openapi: 3.2.0
info:
  title: SocialAPIs Facebook Search API
  version: 1.0.0
  summary: REST API for public Facebook and Instagram data.
  description: 'Public Facebook and Instagram data over one REST API: pages, posts, comments, groups, the Meta Ads Library, Marketplace, Instagram profiles, posts, reels and locations. Authenticate with your API key in the `x-api-token` header. Most calls cost 1 credit; each operation states its price. The free plan includes 200 credits a month. Also available as an MCP server at https://mcp.socialapis.io/mcp.'
  termsOfService: https://socialapis.io/terms
  contact:
    name: SocialAPIs support
    url: https://socialapis.io/contact-us
    email: support@socialapis.io
servers:
- url: https://api.socialapis.io
security:
- ApiKey: []
tags:
- name: Facebook Search
  description: Keyword search for Facebook pages, people, posts, videos and locations.
paths:
  /facebook/search/pages:
    get:
      operationId: facebook_search_pages
      summary: Search for Facebook pages by keyword with optional location filtering
      description: 'Find Facebook pages by keyword (brand, business or topic name), optionally near a location. Returns page names, URLs, categories and follower counts, 3 per call, plus an end_cursor. Use it when you don''t have the page URL; then call facebook_get_page_details with a result''s URL. For locations, get a location_uid from facebook_search_locations. Pricing: 1 credit per call.'
      tags:
      - Facebook Search
      parameters:
      - name: query
        in: query
        required: true
        description: Keyword to search for, e.g. a brand or business name
        schema:
          type: string
      - name: location_uid
        in: query
        required: false
        description: Location UID for filtering (from search/locations endpoint)
        schema:
          type: string
      - name: end_cursor
        in: query
        required: false
        description: Pagination cursor
        schema:
          type: string
      responses:
        '200':
          description: The requested data. Most responses include a `meta` block with `creditsCharged` and `creditsRemaining`.
          headers:
            X-SocialAPIs-Credits-Deducted:
              $ref: '#/components/headers/CreditsDeducted'
            X-SocialAPIs-Credits-Remaining:
              $ref: '#/components/headers/CreditsRemaining'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamError'
        '504':
          $ref: '#/components/responses/UpstreamTimeout'
  /facebook/search/people:
    get:
      operationId: facebook_search_people
      summary: Search for Facebook people/profiles by keyword with optional location filtering
      description: 'Find public Facebook profiles by name or keyword, optionally near a location (location_uid from facebook_search_locations). Returns names, profile URLs and pictures, plus work, education and location where public, and an end_cursor. Pricing: 1 credit per call.'
      tags:
      - Facebook Search
      parameters:
      - name: query
        in: query
        required: true
        description: Name or keyword to search for
        schema:
          type: string
      - name: location_uid
        in: query
        required: false
        description: Location UID for filtering
        schema:
          type: string
      - name: end_cursor
        in: query
        required: false
        description: Pagination cursor
        schema:
          type: string
      responses:
        '200':
          description: The requested data. Most responses include a `meta` block with `creditsCharged` and `creditsRemaining`.
          headers:
            X-SocialAPIs-Credits-Deducted:
              $ref: '#/components/headers/CreditsDeducted'
            X-SocialAPIs-Credits-Remaining:
              $ref: '#/components/headers/CreditsRemaining'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamError'
        '504':
          $ref: '#/components/responses/UpstreamTimeout'
  /facebook/search/locations:
    get:
      operationId: facebook_search_locations
      summary: Search for Facebook locations by keyword
      description: 'Look up Facebook places by name (city, region, venue) and get their location_uid. The location_uid is only used to filter facebook_search_pages, facebook_search_people and facebook_search_posts; it is not a Marketplace location (use facebook_marketplace_city_coordinates for that). Pricing: 1 credit per call.'
      tags:
      - Facebook Search
      parameters:
      - name: query
        in: query
        required: true
        description: Search query (city, place, landmark)
        schema:
          type: string
      responses:
        '200':
          description: The requested data. Most responses include a `meta` block with `creditsCharged` and `creditsRemaining`.
          headers:
            X-SocialAPIs-Credits-Deducted:
              $ref: '#/components/headers/CreditsDeducted'
            X-SocialAPIs-Credits-Remaining:
              $ref: '#/components/headers/CreditsRemaining'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamError'
        '504':
          $ref: '#/components/responses/UpstreamTimeout'
  /facebook/search/posts:
    get:
      operationId: facebook_search_posts
      summary: Search for Facebook posts by keyword with optional location and time filters
      description: 'Search public Facebook posts by keyword, optionally filtered by location (location_uid from facebook_search_locations) and date range. Returns posts with text, author and engagement, plus an end_cursor. To list one page''s posts, use facebook_get_page_posts instead. Pricing: 1 credit per call.'
      tags:
      - Facebook Search
      parameters:
      - name: query
        in: query
        required: true
        description: Keyword or phrase to search post text for
        schema:
          type: string
      - name: location_uid
        in: query
        required: false
        description: Location UID for filtering
        schema:
          type: string
      - name: start_time
        in: query
        required: false
        description: Filter posts after this date (YYYY-MM-DD)
        schema:
          type: string
      - name: end_time
        in: query
        required: false
        description: Filter posts before this date (YYYY-MM-DD)
        schema:
          type: string
      - name: recent_posts
        in: query
        required: false
        description: When "true", shows only recent posts
        schema:
          type: boolean
      - name: end_cursor
        in: query
        required: false
        description: Pagination cursor
        schema:
          type: string
      responses:
        '200':
          description: The requested data. Most responses include a `meta` block with `creditsCharged` and `creditsRemaining`.
          headers:
            X-SocialAPIs-Credits-Deducted:
              $ref: '#/components/headers/CreditsDeducted'
            X-SocialAPIs-Credits-Remaining:
              $ref: '#/components/headers/CreditsRemaining'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamError'
        '504':
          $ref: '#/components/responses/UpstreamTimeout'
  /facebook/search/videos:
    get:
      operationId: facebook_search_videos
      summary: Search for Facebook videos by keyword with optional recency and live filters
      description: 'Search public Facebook videos by keyword, optionally most recent first or live videos only. Returns video titles, URLs and view counts, plus an end_cursor. Pricing: 1 credit per call.'
      tags:
      - Facebook Search
      parameters:
      - name: query
        in: query
        required: true
        description: Keyword or phrase to search videos for
        schema:
          type: string
      - name: most_recent
        in: query
        required: false
        description: When "true", shows most recent videos first
        schema:
          type: boolean
      - name: videos_live
        in: query
        required: false
        description: When "true", filters for live videos only
        schema:
          type: boolean
      - name: fields
        in: query
        required: false
        description: Comma-separated list of response fields to include
        schema:
          type: string
      - name: end_cursor
        in: query
        required: false
        description: Pagination cursor
        schema:
          type: string
      responses:
        '200':
          description: The requested data. Most responses include a `meta` block with `creditsCharged` and `creditsRemaining`.
          headers:
            X-SocialAPIs-Credits-Deducted:
              $ref: '#/components/headers/CreditsDeducted'
            X-SocialAPIs-Credits-Remaining:
              $ref: '#/components/headers/CreditsRemaining'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/UpstreamError'
        '504':
          $ref: '#/components/responses/UpstreamTimeout'
components:
  responses:
    RateLimited:
      description: Rate limit exceeded for your plan. Retry after the limit resets.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UpstreamTimeout:
      description: The data source took too long to respond. No credits are charged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Insufficient credits, expired subscription or paused account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UpstreamError:
      description: The data source returned an error. No credits are charged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: A required parameter is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  headers:
    CreditsRemaining:
      description: Credits left on your account after this call.
      schema:
        type: integer
    CreditsDeducted:
      description: Credits charged for this call.
      schema:
        type: integer
  schemas:
    Error:
      type: object
      properties:
        success:
          type: boolean
        error:
          type: string
        message:
          type: string
        code:
          type: string
      additionalProperties: true
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-token
      description: Your API key from https://socialapis.io/dashboard
externalDocs:
  description: Documentation
  url: https://docs.socialapis.io