twittrapi-com Jobs API

openapi: 3.2.0
info:
  title: TwittrAPI Jobs API
  version: 1.0.0
  summary: Public Twitter/X data over REST, priced per API call.
  description: 'TwittrAPI is a REST API for public Twitter/X data: users, tweets, search, followers, lists, communities, jobs and trends. Pay per call from a prepaid balance; no X developer account needed.


    Authentication: send your key in the X-API-KEY header. Get a key at https://www.twittrapi.com/start (a human signs up; the key can then be given to an agent).


    Responses: X''s raw JSON by default (passthrough), or add format=simple for compact, flat JSON with a fixed schema (same price).


    Account actions (tag "Account actions", /client/* and /premium/*): POST endpoints that act on your own X account with its session cookie and your proxy in the JSON body (https://www.twittrapi.com/docs/x-session). Same price per call as reads; trial keys cannot call them.


    Pricing (machine-readable): https://www.twittrapi.com/pricing.json. All docs in one file: https://www.twittrapi.com/llms-full.txt.


    RapidAPI: the same paths on https://twitter-aio.p.rapidapi.com with the x-rapidapi-key and x-rapidapi-host headers.


    Not affiliated with X Corp. Twitter and X are trademarks of X Corp. Only publicly available data is accessible.'
  contact:
    name: TwittrAPI support
    email: support@twittrapi.com
    url: https://www.twittrapi.com/docs
  termsOfService: https://www.twittrapi.com/terms
  license:
    name: 'Proprietary: use under the terms of service'
    url: https://www.twittrapi.com/terms
servers:
- url: https://api.twittrapi.com
  description: Direct API
- url: https://twitter-aio.p.rapidapi.com
  description: RapidAPI (x-rapidapi-key and x-rapidapi-host headers instead of X-API-KEY)
security:
- ApiKeyAuth: []
tags:
- name: Jobs
  description: Jobs endpoints (read-only GET).
paths:
  /jobs/search/{searchTerm}:
    get:
      operationId: jobsSearchSearchterm
      summary: Search jobs
      description: 'Job listings posted on X, by keyword.


        Paginated: pass the bottom cursor of one page as cursor to get the next. Each page is one billed call.


        X''s job search sometimes fails on X''s side (DependencyError); the API retries automatically and returns an error if every attempt fails. Retrying a little later usually works.


        Reference: https://www.twittrapi.com/docs/reference/jobs-search-searchterm'
      tags:
      - Jobs
      externalDocs:
        url: https://www.twittrapi.com/docs/reference/jobs-search-searchterm
      parameters:
      - name: searchTerm
        in: path
        required: true
        description: Keyword, URL-encoded.
        schema:
          type: string
      - name: count
        in: query
        required: false
        description: Number of jobs to ask X for. Sent to X as is; X treats it as a hint and decides how many it returns (follower and following pages often hold 50 to 70 users for count=20). A value that is not a number falls back to 20.
        schema:
          type: integer
          default: 20
      - name: cursor
        in: query
        required: false
        description: Bottom cursor from the previous page. Leave it out for the first page. See Pagination.
        schema:
          type: string
      - name: jobLocationId
        in: query
        required: false
        description: Location IDs from /jobs/find-location/{term}.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: jobLocationType
        in: query
        required: false
        description: Location types, passed to X unchanged.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: seniorityLevel
        in: query
        required: false
        description: Seniority levels, passed to X unchanged.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: employmentType
        in: query
        required: false
        description: Employment types, passed to X unchanged.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: companyName
        in: query
        required: false
        description: Only jobs from this company.
        schema:
          type: string
      - name: format
        in: query
        required: false
        description: 'raw (default): X''s JSON passed through. simple: flat camelCase JSON with a fixed schema and a {data, nextCursor, previousCursor, hasNextPage} envelope. Same price. The header X-Response-Format: simple does the same.'
        schema:
          type: string
          enum:
          - raw
          - simple
          default: raw
      responses:
        '200':
          description: 'Raw JSON of X''s JobSearchQueryScreenJobsQuery. Jobs are in data.job_search.items_results; the next-page cursor is data.job_search.slice_info.next_cursor.


            With format=simple: Collection of Job objects.'
          headers:
            X-Price-Per-Call:
              description: What this call cost, in USD
              schema:
                type: string
            X-Remaining-Balance:
              description: Balance after this call (and after a refund, if any)
              schema:
                type: string
            X-Refunded:
              description: true when the call was refunded
              schema:
                type: string
            X-Retried:
              description: true when the gateway needed more than one attempt
              schema:
                type: string
            X-Response-Format:
              description: simple when the simple format was returned
              schema:
                type: string
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/JobPage'
                - $ref: '#/components/schemas/RawPassthrough'
                description: 'format=simple: the simple-format schema. Default (raw): X''s JSON, passthrough.'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
  /jobs/{jobId}:
    get:
      operationId: jobsJobid
      summary: Job details
      description: 'One job listing by ID.


        Reference: https://www.twittrapi.com/docs/reference/jobs-jobid'
      tags:
      - Jobs
      externalDocs:
        url: https://www.twittrapi.com/docs/reference/jobs-jobid
      parameters:
      - name: jobId
        in: path
        required: true
        description: Numeric job ID.
        schema:
          type: string
          pattern: ^[0-9]+$
      - name: format
        in: query
        required: false
        description: 'raw (default): X''s JSON passed through. simple: flat camelCase JSON with a fixed schema and a {data, nextCursor, previousCursor, hasNextPage} envelope. Same price. The header X-Response-Format: simple does the same.'
        schema:
          type: string
          enum:
          - raw
          - simple
          default: raw
      responses:
        '200':
          description: 'Raw JSON of X''s JobScreenQuery.


            With format=simple: {data: Job}.'
          headers:
            X-Price-Per-Call:
              description: What this call cost, in USD
              schema:
                type: string
            X-Remaining-Balance:
              description: Balance after this call (and after a refund, if any)
              schema:
                type: string
            X-Refunded:
              description: true when the call was refunded
              schema:
                type: string
            X-Retried:
              description: true when the gateway needed more than one attempt
              schema:
                type: string
            X-Response-Format:
              description: simple when the simple format was returned
              schema:
                type: string
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/JobResult'
                - $ref: '#/components/schemas/RawPassthrough'
                description: 'format=simple: the simple-format schema. Default (raw): X''s JSON, passthrough.'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          description: jobId is not numeric.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
  /jobs/find-location/{term}:
    get:
      operationId: jobsFindLocationTerm
      summary: Find job location
      description: 'Location IDs for the jobLocationId filter of job search. Returns up to 10 matches.


        Reference: https://www.twittrapi.com/docs/reference/jobs-find-location-term'
      tags:
      - Jobs
      externalDocs:
        url: https://www.twittrapi.com/docs/reference/jobs-find-location-term
      parameters:
      - name: term
        in: path
        required: true
        description: Place name, URL-encoded.
        schema:
          type: string
      - name: format
        in: query
        required: false
        description: 'raw (default): X''s JSON passed through. simple: flat camelCase JSON with a fixed schema and a {data, nextCursor, previousCursor, hasNextPage} envelope. Same price. The header X-Response-Format: simple does the same.'
        schema:
          type: string
          enum:
          - raw
          - simple
          default: raw
      responses:
        '200':
          description: 'Raw JSON of X''s LocationSelectorQuery.


            With format=simple: Collection of {id, name} location suggestions (no cursor).'
          headers:
            X-Price-Per-Call:
              description: What this call cost, in USD
              schema:
                type: string
            X-Remaining-Balance:
              description: Balance after this call (and after a refund, if any)
              schema:
                type: string
            X-Refunded:
              description: true when the call was refunded
              schema:
                type: string
            X-Retried:
              description: true when the gateway needed more than one attempt
              schema:
                type: string
            X-Response-Format:
              description: simple when the simple format was returned
              schema:
                type: string
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/JobLocationPage'
                - $ref: '#/components/schemas/RawPassthrough'
                description: 'format=simple: the simple-format schema. Default (raw): X''s JSON, passthrough.'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  responses:
    PaymentRequired:
      description: No balance left, or the trial expired. Not charged. Top up in the dashboard.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or unknown API key. Not charged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: 'Rate limit for your key exceeded. Not charged. No Retry-After header: back off exponentially.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Key deactivated, or the endpoint is not in your plan (trial keys and account actions). Not charged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: Something failed on our side or between us and X. Refunded (400, 407, 408, 409 or a 5xx error are refunded). Retry with backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    JobLocationPage:
      type: object
      description: 'Simple format: location suggestions (no cursor)'
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/JobLocation'
        nextCursor:
          type:
          - string
          - 'null'
          description: Pass as cursor for the next page; null on the last page
        previousCursor:
          type:
          - string
          - 'null'
          description: X's top cursor, for polling newer items
        hasNextPage:
          type: boolean
      required:
      - data
      - nextCursor
      - previousCursor
      - hasNextPage
    Job:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        location:
          type:
          - string
          - 'null'
        url:
          type:
          - string
          - 'null'
          description: The employer's application page
        description:
          type:
          - string
          - 'null'
        company:
          anyOf:
          - type: object
            properties:
              id:
                type: string
              name:
                type: string
              logoUrl:
                type:
                - string
                - 'null'
            required:
            - id
            - name
            - logoUrl
          - type: 'null'
        postedBy:
          anyOf:
          - type: object
            properties:
              id:
                type: string
              username:
                type: string
            required:
            - id
            - username
          - type: 'null'
      required:
      - id
      - title
      - location
      - url
      - description
      - company
      - postedBy
    Error:
      type: object
      properties:
        error:
          type: string
          description: Message. Do not parse it; use the status code.
        errorInfo:
          description: X's raw reply, on some endpoints
        attempts:
          type: integer
          description: Search retries
        errorCode:
          type: string
      required:
      - error
    RawPassthrough:
      type: object
      additionalProperties: true
      description: X's own JSON (raw format, the default), passed through unchanged. The shape is X's and can change; see https://www.twittrapi.com/docs/response-format.
    JobPage:
      type: object
      description: 'Simple format: a page of jobs'
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Job'
        nextCursor:
          type:
          - string
          - 'null'
          description: Pass as cursor for the next page; null on the last page
        previousCursor:
          type:
          - string
          - 'null'
          description: X's top cursor, for polling newer items
        hasNextPage:
          type: boolean
      required:
      - data
      - nextCursor
      - previousCursor
      - hasNextPage
    JobResult:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Job'
      required:
      - data
      description: 'Simple format: one job'
    JobLocation:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
      required:
      - id
      - name
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key from the dashboard (https://app.twittrapi.com/register).
externalDocs:
  description: Documentation
  url: https://www.twittrapi.com/docs