---
title: "Submit search job"
method: POST
path: "/api/{org_id}/search_jobs"
tags: ["Search Jobs"]
---

# Submit search job

`POST /api/{org_id}/search_jobs`

## Request

- Base URL: `https://api.openobserve.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.openobserve.ai/api/{org_id}/search_jobs`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/openobserve/apis/openobserve-api-http/docs/api/:org_id/search_jobs/post.ts> (a function with typed inputs; its response is checked against the schema)

Submits a new asynchronous search job for execution. Search jobs are useful for long-running queries that might exceed normal timeout limits or for scheduling queries to run in the background. The job is queued for execution and returns a job ID that can be used to monitor progress and retrieve results later.

## Path parameters

- `org_id` string, required

## Request body

- object
  - `agent_options` SearchAgentOptions: Agent-oriented response options. When absent the response is unchanged, so existing clients (UI) are unaffected.
    - `mode` 'default' | 'partition'
    - `output_format` 'json' | 'csv' | 'md_table'
  - `clear_cache` boolean
  - `clusters` string[]
  - `encoding` 'base64' | 'Empty'
  - `local_mode` boolean, nullable
  - `query` SearchQuery, required
    - `analyze_profile` boolean: Adds the structured `profile` column to EXPLAIN ANALYZE output.
    - `end_time` integer, required
    - `from` integer
    - `histogram_interval` integer: Seconds; 0 uses the SQL `histogram()` interval, falling back to one from the time range.
    - `query_fn` string, nullable: Base64-encoded VRL program applied to the result hits.
    - `quick_mode` boolean: For `SELECT *` on streams wider than `quick_mode_num_fields`, reads only some columns.
    - `sampling_config` object, nullable
    - `sampling_ratio` number, double, nullable: Simplified sampling API: just specify ratio (0.0-1.0), backend uses optimal defaults Takes precedence over sampling_config if both are provided
    - `size` integer
    - `skip_wal` boolean: Not read by the search path; skipping the WAL is controlled by `feature_query_skip_wal`.
    - `sql` string, required
    - `start_time` integer, required
    - `streaming_id` string, nullable
    - `streaming_output` boolean: Set with `streaming_id` by the streaming search endpoints; other callers leave both unset.
    - `timezone` string, nullable: Default fixed-offset timezone (e.g. "+08:00") applied to histogram() buckets that don't carry their own 3rd timezone argument. None / "UTC" / "" => UTC.
    - `track_total_hits` boolean: Turns the query into a `count(*)` of matching rows; also skips the cache and streaming.
    - `uses_zo_fn` boolean: Set when the SQL calls a saved VRL function, which makes the result hits get flattened.
  - `regions` string[]
  - `search_event_context` SearchEventContext
    - `alert_key` string, nullable
    - `alert_name` string, nullable
    - `dashboard_id` string, nullable
    - `dashboard_name` string, nullable
    - `derived_stream_key` string, nullable
    - `folder_id` string, nullable
    - `folder_name` string, nullable
    - `panel_id` string, nullable
    - `public_dashboard_link_id` string, nullable
    - `range_key` string, nullable
    - `report_id` string, nullable
  - `search_type` 'ui' | 'dashboards' | 'reports' | 'alerts' | 'values' | 'other' | 'rum' | 'derivedstream' | 'searchjob' | 'download' | 'insights' | 'public_dashboard'
  - `timeout` integer
  - `use_cache` boolean
  - `use_index` boolean: Set to false to skip the inverted index for this query.

## Response `200`

Search Job submitted successfully

- HttpResponse: HTTP response code 200 is success code 400 is error code 404 is not found code 500 is internal server error code 503 is service unavailable code >= 1000 is custom error code message is the message or error message
  - `code` integer, required
  - `error_detail` string, nullable
  - `hint` string, nullable: One-line guidance on how to fix the error (agent self-correction, D4).
  - `id` string, nullable
  - `message` string, required
  - `name` string, nullable
  - `suggestions` string[], nullable: Closest valid alternatives for a mistyped field/function name.
  - `trace_id` string, nullable
  - `warnings` string[], nullable: Problems with a request that succeeded anyway. Distinct from `hint`, which explains a failure: these accompany a 200, and the caller is entitled to have meant it.

## Other responses

- `400`: Bad Request
- `500`: Internal Server Error

---

[API](https://skmtc.dev/openobserve/apis/openobserve-api-http.md) - [All operations](https://skmtc.dev/openobserve/apis/openobserve-api-http/llms.txt) - [OpenAPI document](https://skmtc.dev/openobserve/apis/openobserve-api-http/revisions/0529b8a10252?raw)