Splunk Search API

openapi: 3.1.0
info:
  title: Splunk Enterprise REST Data Inputs Search API
  description: The Splunk Enterprise REST API provides programmatic access to Splunk Enterprise functionality including search, indexing, data inputs, and system management. All requests are made over HTTPS to the splunkd management port (default 8089). Authentication is required via Splunk authentication tokens or HTTP Basic authentication with a valid Splunk username and password. Responses are available in JSON and XML formats.
  version: 9.4.0
  contact:
    name: Splunk Inc.
    url: https://www.splunk.com
    email: devinfo@splunk.com
  license:
    name: Splunk Terms of Service
    url: https://www.splunk.com/en_us/legal/splunk-general-terms.html
  x-apisguru-categories:
  - analytics
  - monitoring
  - security
  x-logo:
    url: https://www.splunk.com/content/dam/splunk2/images/icons/favicons/favicon.ico
servers:
- url: https://{host}:{port}
  description: Splunk Enterprise management endpoint
  variables:
    host:
      default: localhost
      description: Hostname or IP address of the Splunk Enterprise instance
    port:
      default: '8089'
      description: splunkd management port
security:
- BearerAuth: []
- BasicAuth: []
tags:
- name: Search
  description: Endpoints for creating, managing, and retrieving search jobs and their results. Splunk search processing language (SPL) queries are submitted as search jobs that run asynchronously.
  externalDocs:
    url: https://docs.splunk.com/Documentation/Splunk/latest/RESTREF/RESTsearch
paths:
  /services/search/jobs:
    get:
      operationId: listSearchJobs
      summary: List Search Jobs
      description: Returns a list of current search jobs for the authenticated user. Includes job status, progress, and metadata for each job.
      tags:
      - Search
      parameters:
      - $ref: '#/components/parameters/OutputMode'
      - $ref: '#/components/parameters/Count'
      - $ref: '#/components/parameters/Offset'
      - name: search
        in: query
        description: Filter search jobs by search string
        schema:
          type: string
        example: example_value
      - name: sort_key
        in: query
        description: Field to sort by
        schema:
          type: string
          default: dispatch_time
        example: example_value
      - name: sort_dir
        in: query
        description: Sort direction
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
        example: asc
      responses:
        '200':
          description: List of search jobs returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchJobList'
              examples:
                Listsearchjobs200Example:
                  summary: Default listSearchJobs 200 response
                  x-microcks-default: true
                  value:
                    origin: example_value
                    updated: '2026-01-15T10:30:00Z'
                    generator:
                      build: example_value
                      version: example_value
                    entry:
                    - sid: '500123'
                      content: {}
                    paging:
                      total: 10
                      perPage: 10
                      offset: 10
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createSearchJob
      summary: Create a Search Job
      description: Creates a new search job. The search job runs asynchronously. Use the returned search ID (sid) to check job status and retrieve results. Searches use the Splunk Search Processing Language (SPL).
      tags:
      - Search
      parameters:
      - $ref: '#/components/parameters/OutputMode'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SearchJobCreateRequest'
            examples:
              CreatesearchjobRequestExample:
                summary: Default createSearchJob request
                x-microcks-default: true
                value:
                  search: example_value
                  earliest_time: example_value
                  latest_time: example_value
                  search_mode: normal
                  exec_mode: normal
                  max_count: 10
                  max_time: 10
                  timeout: 10
                  rf: example_value
                  namespace: example_value
                  id: abc123
                  status_buckets: 10
                  auto_cancel: 10
                  auto_finalize_ec: 10
                  auto_pause: 10
                  enable_lookups: true
                  reload_macros: true
                  reduce_freq: 10
                  spawn_process: true
      responses:
        '201':
          description: Search job created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  sid:
                    type: string
                    description: The search ID assigned to the new search job
                    examples:
                    - '1234567890.12345'
              examples:
                Createsearchjob201Example:
                  summary: Default createSearchJob 201 response
                  x-microcks-default: true
                  value:
                    sid: '500123'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /services/search/jobs/{search_id}:
    get:
      operationId: getSearchJob
      summary: Get Search Job Details
      description: Returns detailed information about a specific search job including its status, progress, performance metrics, and configuration.
      tags:
      - Search
      parameters:
      - $ref: '#/components/parameters/SearchId'
      - $ref: '#/components/parameters/OutputMode'
      responses:
        '200':
          description: Search job details returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchJob'
              examples:
                Getsearchjob200Example:
                  summary: Default getSearchJob 200 response
                  x-microcks-default: true
                  value:
                    sid: '500123'
                    content:
                      sid: '500123'
                      dispatchState: QUEUED
                      doneProgress: 42.5
                      scanCount: 10
                      eventCount: 10
                      resultCount: 10
                      runDuration: 42.5
                      earliestTime: '2026-01-15T10:30:00Z'
                      latestTime: '2026-01-15T10:30:00Z'
                      cursorTime: '2026-01-15T10:30:00Z'
                      eventSearch: example_value
                      reportSearch: example_value
                      isSaved: true
                      isFinalized: true
                      isPaused: true
                      isZombie: true
                      isDone: true
                      isFailed: true
                      isPreviewEnabled: true
                      isRealTimeSearch: true
                      isSavedSearch: true
                      isRemoteTimeline: true
                      priority: 10
                      ttl: 10
                      request: example_value
                      performance: example_value
                      messages:
                      - type: DEBUG
                        text: example_value
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteSearchJob
      summary: Delete a Search Job
      description: Cancels and deletes the specified search job and its results.
      tags:
      - Search
      parameters:
      - $ref: '#/components/parameters/SearchId'
      responses:
        '200':
          description: Search job deleted successfully
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /services/search/jobs/{search_id}/control:
    post:
      operationId: controlSearchJob
      summary: Control a Search Job
      description: Execute a control action on a search job such as pause, unpause, finalize, cancel, or touch (extend the job lifetime).
      tags:
      - Search
      parameters:
      - $ref: '#/components/parameters/SearchId'
      - $ref: '#/components/parameters/OutputMode'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - action
              properties:
                action:
                  type: string
                  description: The control action to execute
                  enum:
                  - pause
                  - unpause
                  - finalize
                  - cancel
                  - touch
                  - setttl
                  - setpriority
                  - enablepreview
                  - disablepreview
                ttl:
                  type: integer
                  description: Time to live in seconds (used with setttl action)
                priority:
                  type: integer
                  description: Priority value 0-10 (used with setpriority action)
                  minimum: 0
                  maximum: 10
            examples:
              ControlsearchjobRequestExample:
                summary: Default controlSearchJob request
                x-microcks-default: true
                value:
                  action: pause
                  ttl: 10
                  priority: 10
      responses:
        '200':
          description: Control action executed successfully
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /services/search/jobs/{search_id}/results:
    get:
      operationId: getSearchResults
      summary: Get Search Results
      description: Returns the results of a completed search job. Results are available only after the search job has finished. Use the count and offset parameters for pagination.
      tags:
      - Search
      parameters:
      - $ref: '#/components/parameters/SearchId'
      - $ref: '#/components/parameters/OutputMode'
      - $ref: '#/components/parameters/Count'
      - $ref: '#/components/parameters/Offset'
      - name: search
        in: query
        description: Post-processing search string to filter results
        schema:
          type: string
        example: example_value
      - name: field_list
        in: query
        description: Comma-separated list of fields to return
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: Search results returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResults'
              examples:
                Getsearchresults200Example:
                  summary: Default getSearchResults 200 response
                  x-microcks-default: true
                  value:
                    init_offset: 10
                    results:
                    - {}
                    fields:
                    - name: Example Title
                      type: example_value
                    messages:
                    - type: example_value
                      text: example_value
                    preview: true
                    highlighted: example_value
        '204':
          description: Search job has not yet finished; no results available
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /services/search/jobs/{search_id}/events:
    get:
      operationId: getSearchEvents
      summary: Get Search Events
      description: Returns the untransformed events of a search job. Unlike results, events return the raw data before any transforming commands are applied. Available for searches that include non-transforming commands.
      tags:
      - Search
      parameters:
      - $ref: '#/components/parameters/SearchId'
      - $ref: '#/components/parameters/OutputMode'
      - $ref: '#/components/parameters/Count'
      - $ref: '#/components/parameters/Offset'
      - name: earliest_time
        in: query
        description: Earliest time boundary for events
        schema:
          type: string
        example: example_value
      - name: latest_time
        in: query
        description: Latest time boundary for events
        schema:
          type: string
        example: example_value
      - name: search
        in: query
        description: Post-processing search to filter events
        schema:
          type: string
        example: example_value
      - name: field_list
        in: query
        description: Comma-separated list of fields to return
        schema:
          type: string
        example: example_value
      - name: truncation_mode
        in: query
        description: How to truncate long lines
        schema:
          type: string
          enum:
          - abstract
          - truncate
        example: abstract
      - name: max_lines
        in: query
        description: Maximum number of lines per event
        schema:
          type: integer
          default: 0
        example: 10
      responses:
        '200':
          description: Search events returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResults'
              examples:
                Getsearchevents200Example:
                  summary: Default getSearchEvents 200 response
                  x-microcks-default: true
                  value:
                    init_offset: 10
                    results:
                    - {}
                    fields:
                    - name: Example Title
                      type: example_value
                    messages:
                    - type: example_value
                      text: example_value
                    preview: true
                    highlighted: example_value
        '204':
          description: No events available yet
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /services/search/jobs/export:
    get:
      operationId: exportSearchResults
      summary: Export Search Results
      description: Runs a search and streams results back as they become available, rather than waiting for the search to complete. This is a streaming endpoint suitable for long-running searches or real-time searches. The search runs synchronously and results stream back in the response.
      tags:
      - Search
      parameters:
      - name: search
        in: query
        required: true
        description: The SPL search query to execute
        schema:
          type: string
        example: example_value
      - $ref: '#/components/parameters/OutputMode'
      - name: earliest_time
        in: query
        description: Earliest time for the search
        schema:
          type: string
        example: example_value
      - name: latest_time
        in: query
        description: Latest time for the search
        schema:
          type: string
        example: example_value
      - name: auto_cancel
        in: query
        description: Seconds of inactivity after which the search is cancelled
        schema:
          type: integer
        example: 10
      - name: enable_lookups
        in: query
        description: Whether to enable lookups during the search
        schema:
          type: boolean
          default: true
        example: true
      responses:
        '200':
          description: Search results streaming successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResults'
              examples:
                Exportsearchresults200Example:
                  summary: Default exportSearchResults 200 response
                  x-microcks-default: true
                  value:
                    init_offset: 10
                    results:
                    - {}
                    fields:
                    - name: Example Title
                      type: example_value
                    messages:
                    - type: example_value
                      text: example_value
                    preview: true
                    highlighted: example_value
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    SearchJob:
      type: object
      properties:
        sid:
          type: string
          description: The unique search ID
          example: '500123'
        content:
          type: object
          properties:
            sid:
              type: string
            dispatchState:
              type: string
              description: Current state of the search job
              enum:
              - QUEUED
              - PARSING
              - RUNNING
              - PAUSED
              - FINALIZING
              - DONE
              - FAILED
            doneProgress:
              type: number
              description: Progress percentage (0.0 to 1.0)
              minimum: 0
              maximum: 1
            scanCount:
              type: integer
              description: Number of events scanned so far
            eventCount:
              type: integer
              description: Number of events returned
            resultCount:
              type: integer
              description: Number of results produced
            runDuration:
              type: number
              description: Time elapsed in seconds
            earliestTime:
              type: string
              format: date-time
              description: Earliest time boundary of the search
            latestTime:
              type: string
              format: date-time
              description: Latest time boundary of the search
            cursorTime:
              type: string
              format: date-time
              description: Current time position of the search cursor
            eventSearch:
              type: string
              description: The search string applied to events
            reportSearch:
              type: string
              description: The reporting search string
            isSaved:
              type: boolean
            isFinalized:
              type: boolean
            isPaused:
              type: boolean
            isZombie:
              type: boolean
            isDone:
              type: boolean
            isFailed:
              type: boolean
            isPreviewEnabled:
              type: boolean
            isRealTimeSearch:
              type: boolean
            isSavedSearch:
              type: boolean
            isRemoteTimeline:
              type: boolean
            priority:
              type: integer
              description: Job priority (0-10)
            ttl:
              type: integer
              description: Time to live in seconds
            request:
              type: object
              description: Original request parameters
            performance:
              type: object
              description: Performance metrics for the search
            messages:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                    - DEBUG
                    - INFO
                    - WARN
                    - ERROR
                    - FATAL
                  text:
                    type: string
          example: example_value
    Paging:
      type: object
      properties:
        total:
          type: integer
          description: Total number of items available
          example: 10
        perPage:
          type: integer
          description: Number of items per page
          example: 10
        offset:
          type: integer
          description: Current offset
          example: 10
    SearchJobCreateRequest:
      type: object
      required:
      - search
      properties:
        search:
          type: string
          description: The SPL search query to execute
          examples:
          - search index=main sourcetype=syslog | head 100
        earliest_time:
          type: string
          description: Earliest time for the search using relative or absolute time format
          examples:
          - -24h@h
          - '2024-01-01T00:00:00.000Z'
        latest_time:
          type: string
          description: Latest time for the search
          examples:
          - now
        search_mode:
          type: string
          description: The search mode
          enum:
          - normal
          - realtime
          default: normal
          example: normal
        exec_mode:
          type: string
          description: Execution mode. Normal runs asynchronously, oneshot runs synchronously, blocking waits for completion.
          enum:
          - normal
          - blocking
          - oneshot
          default: normal
          example: normal
        max_count:
          type: integer
          description: Maximum number of results to return
          default: 10000
          example: 10
        max_time:
          type: integer
          description: Maximum time in seconds before the search is finalized
          default: 0
          example: 10
        timeout:
          type: integer
          description: Number of seconds to keep the search after processing has stopped
          default: 86400
          example: 10
        rf:
          type: string
          description: Comma-separated list of required fields to include in results
          example: example_value
        namespace:
          type: string
          description: Application namespace for the search
          example: example_value
        id:
          type: string
          description: Optional custom search ID. If not specified, Splunk generates one automatically.
          example: abc123
        status_buckets:
          type: integer
          description: Number of status buckets to generate for the search timeline. Set to a value greater than 0 to enable timeline.
          default: 0
          example: 10
        auto_cancel:
          type: integer
          description: Seconds of inactivity after which the search is automatically cancelled. 0 means never auto-cancel.
          default: 0
          example: 10
        auto_finalize_ec:
          type: integer
          description: Auto-finalize the search after this number of events have been processed. 0 disables auto-finalize.
          default: 0
          example: 10
        auto_pause:
          type: integer
          description: Seconds of inactivity after which the search is automatically paused. 0 means never auto-pause.
          default: 0
          example: 10
        enable_lookups:
          type: boolean
          description: Whether to enable lookups during the search
          default: true
          example: true
        reload_macros:
          type: boolean
          description: Whether to reload macro definitions before the search
          default: true
          example: true
        reduce_freq:
          type: integer
          description: How frequently to invoke the reduce phase (seconds)
          default: 0
          example: 10
        spawn_process:
          type: boolean
          description: Whether to run the search in a separate process
          default: true
          example: true
    ErrorResponse:
      type: object
      properties:
        messages:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - ERROR
                - WARN
                - INFO
              text:
                type: string
                description: Error message text
          example: []
    SearchResults:
      type: object
      properties:
        init_offset:
          type: integer
          description: Starting offset of results
          example: 10
        results:
          type: array
          description: Array of result rows
          items:
            type: object
            additionalProperties: true
            description: Each result is a key-value object where keys are field names and values are field values
          example: []
        fields:
          type: array
          description: Metadata about the fields in the results
          items:
            type: object
            properties:
              name:
                type: string
              type:
                type: string
          example: []
        messages:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              text:
                type: string
          example: []
        preview:
          type: boolean
          description: Whether results are preview (partial) results
          example: true
        highlighted:
          type: object
          description: Highlighted terms in results
          example: example_value
    SearchJobList:
      type: object
      properties:
        origin:
          type: string
          description: URI of the request
          example: example_value
        updated:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        generator:
          type: object
          properties:
            build:
              type: string
            version:
              type: string
          example: example_value
        entry:
          type: array
          items:
            $ref: '#/components/schemas/SearchJob'
          example: []
        paging:
          $ref: '#/components/schemas/Paging'
  parameters:
    Count:
      name: count
      in: query
      description: Maximum number of items to return. A value of 0 returns all items.
      schema:
        type: integer
        default: 30
        minimum: 0
    Offset:
      name: offset
      in: query
      description: Index of the first item to return. Used with count for pagination.
      schema:
        type: integer
        default: 0
        minimum: 0
    OutputMode:
      name: output_mode
      in: query
      description: Response format
      schema:
        type: string
        enum:
        - json
        - xml
        - csv
        default: xml
    SearchId:
      name: search_id
      in: path
      required: true
      description: The search ID (sid) of the search job
      schema:
        type: string
  responses:
    Forbidden:
      description: The authenticated user does not have permission to perform this operation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication credentials are missing, invalid, or expired
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: The request is malformed or contains invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Splunk authentication token. Obtain a session key by authenticating to /services/auth/login or use a pre-configured bearer token from Settings > Tokens in Splunk Web.
    BasicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication with a valid Splunk username and password. The credentials are sent as a Base64-encoded string in the Authorization header.
    HecToken:
      type: apiKey
      in: header
      name: Authorization
      description: HTTP Event Collector token. Send as "Splunk <token>" in the Authorization header. Tokens are configured in Splunk Web under Settings > Data Inputs > HTTP Event Collector.
externalDocs:
  description: Splunk Enterprise REST API Reference
  url: https://docs.splunk.com/Documentation/Splunk/latest/RESTREF/RESTprolog