Splunk

Install the Splunk app first. HEC needs write permission. SPL search needs read permission. Saved searches and snapshots use user credentials.

The Splunk app enables both the Splunk HEC-compatible ingestion endpoints and The service's SPL search API for a cluster. SPL searches run inside RawTree against the selected database's splunk_events table; they do not install or require a Splunk search provider, command, or add-on.

GET /v1/spl/capabilities

Return the static SPL language manifest for this backend version. The response describes supported commands and their valid pipeline positions, functions, operators, keywords, literals, timechart span units, built-in fields, and compiler limits. Clients can fetch it once and compute contextual completion locally; no organization, cluster, database, or authentication selector is required. Database column names are intentionally separate and remain available through the table-description API.

No authentication required.

Request:

# Describe the SPL language subset supported by this RawTree backend.
curl -X GET "https://api.rawtree.com/v1/spl/capabilities"

Expected response: HTTP 200 (excerpt).

{
  "schema_version": 1,
  "language_version": "spl-v1"
}

POST /v1/spl/search

Execute a supported, read-only SPL search. A readable cluster API key uses its bound organization, cluster, and database when those selectors are omitted. With a user or OAuth token, pass the organization, cluster, and database. As on other data endpoints, x-rawtree-database can select the database instead of the database query parameter.

POST /v1/spl/search?organization=acme&cluster=production&database=logs
Authorization: Bearer rt_...

{
  "spl": "index=bot_traffic endpoint=\"/api/login\" action=blocked | sort - _time",
  "earliest": "-30m",
  "latest": "now",
  "include_field_statistics": true,
  "query_id": "optional-client-query-id"
}

Time bounds accept non-negative epoch seconds, now, or a negative relative value such as -30m, -24h, or -7d. The service applies the same read-only query safeguards and cancellation ownership rules as the SQL query API. Cancel a running request with POST /v1/query/cancel using the same query_id, organization, and database scope.

The supported SPL subset covers base searches and search/where boolean filters; positive fields/table; rename; bounded eval; stats with count, dc, sum, avg, values, min, max, earliest, and latest plus optional BY; chart; sort; head; multi-field dedup; and timechart with multiple aggregates and an optional split field. count(eval(<condition>)) is supported; other aggregate eval expressions are not. Unsupported or ambiguous commands return 400 instead of being passed through as SQL.

stats ... BY a b produces rows grouped by both fields. chart ... OVER a BY b (also chart ... BY a b) produces rows for a and separate series columns for b. Split timechart produces the same wide series layout with _time as the first column. With multiple aggregates, series names are <aggregate>:<value>; an explicit AS alias replaces the aggregate name. Quote output field names containing punctuation, for example table _time 'mean:US'. These columns exist before downstream SPL stages run. The response marks this layout with result_format: "native_columns"; older snapshots without this marker retain their legacy rendering behavior.

Both chart commands support limit=N (default 10), limit=topN, limit=bottomN, limit=0 (all series within the safety bound), useother=true|false, and usenull=true|false. Excluded series are combined as OTHER and null split values appear as NULL by default. Series ranking uses the sum of per-row aggregate values for one aggregate, or event frequency for multiple aggregates. The compiler discovers series through bounded read-only SQL, then aggregates the selected series through the same scoped query execution and cancellation path. At most 20 aggregates and 100 output series columns are allowed; excessive series or colliding output names return 400 rather than silently dropping data.

timechart accepts span intervals in s, m, h, d, or w, from 1 second through 31 days, and bins=N (default 100) for automatic span selection. Automatic spans use a bounded interval ladder across the requested window, not every Splunk calendar/span option. cont=true fills missing buckets by default; cont=false returns only observed buckets. Counts fill with zero; absent sums and averages remain null. More than 10,000 continuous buckets require a larger span or smaller window. minspan, calendar-month spans, custom NULL/OTHER labels, and explicit series where clauses are not supported.

The JSON response includes the standard query meta, data, rows, and statistics fields, plus the original spl, a bounded, chronologically ordered timeline, a result_kind of events or statistics, a truncated flag, and an entry for every pipeline segment in source order. Execution uses Smart mode: event-preserving searches produce events and a timeline; transforming searches (stats, chart, timechart, and table) produce statistical results with an empty timeline and no raw_events or event field_statistics. There is no Fast/Verbose mode request option. Timeline buckets for event searches are zero-filled across the requested window (or the recent default window when no time bounds are supplied), with granularity selected to keep the series bounded. Each stage has command, expression, output_rows, and truncated fields. output_rows is the row count after that stage. It is capped at 10,000; truncated: true means a 10,001st row proved that the real count is larger, while exactly 10,000 rows remain exact with truncated: false.

Set include_field_statistics to true to include field_statistics for the event fields produced by the search. Each entry contains the inferred field type, total matching rows, non-null value count, coverage, exact distinct-value count, the five most common values with exact counts, and the source indexes or tables in which the field was found. These statistics are calculated in RawTree across the complete filtered event population; the 10,000-row result limit applies only to rows returned in data. This option is ignored for transforming searches in Smart mode. The dashboard SPL editor uses these common values as field-specific suggestions on the right-hand side of search and where comparisons. They are ranked hints, not an exhaustive list of valid values.

The SPL service measures cardinality-changing stages and carries exact counts across row-preserving stages. Measurement is limited to the first 12 stages and to the generated-query size budget, so output_rows is null when a stage cannot be measured safely. Clients should calculate percentages only for consecutive stages whose counts are non-null and untruncated, where the previous count is positive and the current count does not exceed it. In that case, kept percent is current / previous * 100, affected rows is previous - current, and affected percent is 100 - kept percent; percentage values use the 0–100 range.

Search execution is synchronous: the response is returned after the result, optional raw-event and field-statistics queries, and the bounded analysis query for timeline and stage feedback complete. Every query uses the same authorization, database scope, read-only validation, execution limits, and cancellation ownership.

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in Authentication.

Parameters:

Request:

# Execute the supported SPL v1 subset over splunk_events.
curl -X POST "https://api.rawtree.com/v1/spl/search" \
  -H "Authorization: Bearer $RAWTREE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "spl": "index=events | head 10",
  "earliest": "-1h",
  "latest": "now"
}'

Expected response: HTTP 200.

{
  "meta": [],
  "data": [],
  "rows": 0,
  "statistics": {
    "elapsed": 0.001,
    "rows_read": 0,
    "bytes_read": 0
  },
  "spl": "index=events | head 10",
  "stages": [
    {
      "command": "search",
      "expression": "index=events",
      "truncated": false
    },
    {
      "command": "head",
      "expression": "10",
      "truncated": false
    }
  ],
  "timeline": [],
  "result_kind": "events",
  "truncated": false
}

Errors: 400, 401, 403, 408, 413, 422, 429. See API errors.

Saved searches

Saved searches are scoped to an organization and cluster. Private searches are visible only to their creator; shared searches are available to authenticated members of the same organization while the Splunk app is installed:

Pass organization and cluster on every saved-search request. List requests also accept search, created_by, database, and visibility filters. New searches default to private; set visibility to shared to share one with other authorized organization members. The complete record persists its SPL, time window, selected table or chart visualization, time-series span in minutes, and whether the result table remains available. The list returns metadata for at most 200 searches and sets truncated when additional matches exist; fetch one search to read its complete configuration. Uninstalling the Splunk app disables HEC, SPL execution, and saved-search access but preserves saved-search records and ingested data. Reinstalling the app makes them available again; SQL access is unaffected.

GET /v1/apps/splunk/searches

List saved Splunk searches for a cluster.

Use a user session or user OAuth token with full_access. API keys and workload tokens cannot use this method.

Parameters:

Request:

# List saved Splunk searches for a cluster.
curl -X GET "https://api.rawtree.com/v1/apps/splunk/searches?organization=team_alpha&cluster=production" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN"

Expected response: HTTP 200.

{
  "searches": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "database": "analytics",
      "name": "recent-events",
      "description": "",
      "visibility": "private",
      "created_at": "2026-11-09T10:00:00Z",
      "updated_at": "2026-11-09T10:00:00Z"
    }
  ],
  "truncated": false
}

Errors: 400, 401, 403, 404. See API errors.

POST /v1/apps/splunk/searches

Create a saved Splunk search.

Use a user session or user OAuth token with full_access. API keys and workload tokens cannot use this method.

Parameters:

Request:

# Create a saved Splunk search.
curl -X POST "https://api.rawtree.com/v1/apps/splunk/searches?organization=team_alpha&cluster=production" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "database": "analytics",
  "name": "recent-events",
  "spl": "index=events | head 10"
}'

Expected response: HTTP 201.

{
  "search": {
    "id": "11111111-1111-4111-8111-111111111111",
    "database": "analytics",
    "name": "recent-events",
    "description": "",
    "spl": "index=events | head 10",
    "earliest": "-24h",
    "latest": "now",
    "visibility": "private",
    "visualization": "table",
    "visualization_span_minutes": 60,
    "show_table": true,
    "visualization_config": {},
    "created_at": "2026-11-09T10:00:00Z",
    "updated_at": "2026-11-09T10:00:00Z"
  }
}

Errors: 400, 401, 403, 404. See API errors.

GET /v1/apps/splunk/searches/{search_id}

Get a saved Splunk search.

Use a user session or user OAuth token with full_access. API keys and workload tokens cannot use this method.

Parameters:

Request:

# Get a saved Splunk search.
curl -X GET "https://api.rawtree.com/v1/apps/splunk/searches/11111111-1111-4111-8111-111111111111?organization=team_alpha&cluster=production" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN"

Expected response: HTTP 200.

{
  "search": {
    "id": "11111111-1111-4111-8111-111111111111",
    "database": "analytics",
    "name": "recent-events",
    "description": "",
    "spl": "index=events | head 10",
    "earliest": "-24h",
    "latest": "now",
    "visibility": "private",
    "visualization": "table",
    "visualization_span_minutes": 60,
    "show_table": true,
    "visualization_config": {},
    "created_at": "2026-11-09T10:00:00Z",
    "updated_at": "2026-11-09T10:00:00Z"
  }
}

Errors: 400, 401, 403, 404. See API errors.

DELETE /v1/apps/splunk/searches/{search_id}

Delete a saved Splunk search.

Use a user session or user OAuth token with full_access. API keys and workload tokens cannot use this method.

Parameters:

Request:

# Delete a saved Splunk search.
curl -X DELETE "https://api.rawtree.com/v1/apps/splunk/searches/11111111-1111-4111-8111-111111111111?organization=team_alpha&cluster=production" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN"

Expected response: HTTP 200.

{
  "deleted": true
}

Errors: 400, 401, 403, 404. See API errors.

PATCH /v1/apps/splunk/searches/{search_id}

Update a saved Splunk search.

Use a user session or user OAuth token with full_access. API keys and workload tokens cannot use this method.

Parameters:

Request:

# Update a saved Splunk search.
curl -X PATCH "https://api.rawtree.com/v1/apps/splunk/searches/11111111-1111-4111-8111-111111111111?organization=team_alpha&cluster=production" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "recent-events-updated"
}'

Expected response: HTTP 200.

{
  "search": {
    "id": "11111111-1111-4111-8111-111111111111",
    "database": "analytics",
    "name": "recent-events",
    "description": "",
    "spl": "index=events | head 10",
    "earliest": "-24h",
    "latest": "now",
    "visibility": "private",
    "visualization": "table",
    "visualization_span_minutes": 60,
    "show_table": true,
    "visualization_config": {},
    "created_at": "2026-11-09T10:00:00Z",
    "updated_at": "2026-11-09T10:00:00Z"
  }
}

Errors: 400, 401, 403, 404. See API errors.

GET /v1/apps/splunk/snapshots

List private and shared snapshots without loading result payloads.

Use a user session or user OAuth token with full_access. API keys and workload tokens cannot use this method.

Parameters:

Request:

# List private and shared snapshots without loading result payloads.
curl -X GET "https://api.rawtree.com/v1/apps/splunk/snapshots?organization=team_alpha&cluster=production" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN"

Expected response: HTTP 200.

{
  "snapshots": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "event-snapshot",
      "visibility": "private",
      "created_at": "2026-11-09T10:00:00Z",
      "document_size_bytes": 1024
    }
  ]
}

POST /v1/apps/splunk/snapshots

Preserve a completed SPL result, inheriting the source visibility.

Use a user session or user OAuth token with full_access. API keys and workload tokens cannot use this method.

Parameters:

Request:

# Preserve a completed SPL result, inheriting the source visibility.
curl -X POST "https://api.rawtree.com/v1/apps/splunk/snapshots?organization=team_alpha&cluster=production" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "event-snapshot",
  "document": {
    "schema_version": 1,
    "renderer_version": 1,
    "query": {
      "database": "analytics",
      "earliest": "-1h",
      "latest": "now",
      "executed_at": "2026-11-09T10:00:00Z",
      "completed_at": "2026-11-09T10:00:00Z"
    },
    "result": {
      "meta": [],
      "data": [],
      "rows": 0,
      "statistics": {
        "elapsed": 0.001,
        "rows_read": 0,
        "bytes_read": 0
      },
      "spl": "index=events | head 10",
      "stages": [
        {
          "command": "search",
          "expression": "index=events",
          "truncated": false
        },
        {
          "command": "head",
          "expression": "10",
          "truncated": false
        }
      ],
      "timeline": [],
      "result_kind": "events",
      "truncated": false
    },
    "presentation": {
      "active_tab": "raw-events",
      "active_view": "table",
      "visualization_span": "1m",
      "show_table": true,
      "visualization_config": {}
    }
  }
}'

Expected response: HTTP 201.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "event-snapshot",
  "visibility": "private",
  "created_at": "2026-11-09T10:00:00Z",
  "document_size_bytes": 1024
}

Errors: 400, 413. See API errors.

GET /v1/apps/splunk/snapshots/{snapshot_id}

Load a snapshot without executing its query.

Use a user session or user OAuth token with full_access. API keys and workload tokens cannot use this method.

Parameters:

Request:

# Load a snapshot without executing its query.
curl -X GET "https://api.rawtree.com/v1/apps/splunk/snapshots/11111111-1111-4111-8111-111111111111?organization=team_alpha&cluster=production" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN"

Expected response: HTTP 200.

{
  "snapshot": {
    "id": "11111111-1111-4111-8111-111111111111",
    "name": "event-snapshot",
    "visibility": "private",
    "created_at": "2026-11-09T10:00:00Z",
    "document_size_bytes": 1024
  },
  "document": {
    "schema_version": 1,
    "renderer_version": 1,
    "query": {
      "database": "analytics",
      "earliest": "-1h",
      "latest": "now",
      "executed_at": "2026-11-09T10:00:00Z",
      "completed_at": "2026-11-09T10:00:00Z"
    },
    "result": {
      "meta": [],
      "data": [],
      "rows": 0,
      "statistics": {
        "elapsed": 0.001,
        "rows_read": 0,
        "bytes_read": 0
      },
      "spl": "index=events | head 10",
      "stages": [
        {
          "command": "search",
          "expression": "index=events",
          "truncated": false
        },
        {
          "command": "head",
          "expression": "10",
          "truncated": false
        }
      ],
      "timeline": [],
      "result_kind": "events",
      "truncated": false
    },
    "presentation": {
      "active_tab": "raw-events",
      "active_view": "table",
      "visualization_span": "1m",
      "show_table": true,
      "visualization_config": {}
    }
  }
}

Errors: 404. See API errors.

DELETE /v1/apps/splunk/snapshots/{snapshot_id}

Delete an accessible private or shared snapshot.

Use a user session or user OAuth token with full_access. API keys and workload tokens cannot use this method.

Parameters:

Request:

# Delete an accessible private or shared snapshot.
curl -X DELETE "https://api.rawtree.com/v1/apps/splunk/snapshots/11111111-1111-4111-8111-111111111111?organization=team_alpha&cluster=production" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN"

Expected response: HTTP 204.

The response body is empty.

Errors: 404. See API errors.

PATCH /v1/apps/splunk/snapshots/{snapshot_id}

Change snapshot visibility without modifying captured data.

Use a user session or user OAuth token with full_access. API keys and workload tokens cannot use this method.

Parameters:

Request:

# Change snapshot visibility without modifying captured data.
curl -X PATCH "https://api.rawtree.com/v1/apps/splunk/snapshots/11111111-1111-4111-8111-111111111111?organization=team_alpha&cluster=production" \
  -H "Authorization: Bearer $RAWTREE_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "visibility": "shared"
}'

Expected response: HTTP 200.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "event-snapshot",
  "visibility": "private",
  "created_at": "2026-11-09T10:00:00Z",
  "document_size_bytes": 1024
}

Errors: 404. See API errors.

HEC request fields

The event endpoint accepts HEC JSON events. event is required. Metadata fields include index, host, source, sourcetype, and time. The raw endpoint accepts text. It requires a UUID channel in channel or X-Splunk-Request-Channel. Its URL parameters can supply the same event metadata. index selects the destination table.

Successful ingestion returns code 0. Health returns code 17. Invalid authentication, payloads, or channels return native HEC error codes. A paused cluster returns code 9. HEC query-string authentication is not supported.

POST /splunk/services/collector/

Ingest HEC events.

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in Authentication.

Request:

# Ingest HEC events.
curl -X POST "https://api.rawtree.com/splunk/services/collector/" \
  -H "Authorization: Splunk $RAWTREE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "event": {
    "action": "page_view"
  },
  "index": "events"
}'

Expected response: HTTP 200.

{
  "text": "Success",
  "code": 0
}

POST /splunk/services/collector/event

Ingest HEC events.

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in Authentication.

Request:

# Ingest HEC events.
curl -X POST "https://api.rawtree.com/splunk/services/collector/event" \
  -H "Authorization: Splunk $RAWTREE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "event": {
    "action": "page_view"
  },
  "index": "events"
}'

Expected response: HTTP 200.

{
  "text": "Success",
  "code": 0
}

POST /splunk/services/collector/raw

Ingest raw text.

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in Authentication.

Request:

# Ingest raw text.
curl -X POST "https://api.rawtree.com/splunk/services/collector/raw?index=events&channel=11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Splunk $RAWTREE_API_KEY" \
  -H "Content-Type: text/plain" \
  -d 'service started'

Expected response: HTTP 200.

{
  "text": "Success",
  "code": 0
}

GET /splunk/services/collector/health

Check Splunk HEC health.

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in Authentication.

Request:

# Check Splunk HEC health.
curl -X GET "https://api.rawtree.com/splunk/services/collector/health" \
  -H "Authorization: Splunk $RAWTREE_API_KEY"

Expected response: HTTP 200.

{
  "text": "HEC is healthy",
  "code": 17
}

GET /splunk/services/collector/health/1.0

Check Splunk HEC health.

Use an API key, a permitted workload token, or a user bearer token. Database-role keys support only the operations listed in Authentication.

Request:

# Check Splunk HEC health.
curl -X GET "https://api.rawtree.com/splunk/services/collector/health/1.0" \
  -H "Authorization: Splunk $RAWTREE_API_KEY"

Expected response: HTTP 200.

{
  "text": "HEC is healthy",
  "code": 17
}