> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cotool.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Splunk Integration

> Connect Cotool to Splunk so agents can discover your data, run SPL searches, and manage saved-search detections

## Overview

The Splunk integration lets Cotool agents investigate and hunt in your Splunk data. It provides:

1. **Data discovery** — list indexes and sourcetypes, and get the exact field names, types, and example values for a sourcetype before writing SPL.
2. **SPL searches** — run ad-hoc search jobs over explicit time ranges and page through their results.
3. **Detections** — list Splunk saved searches and create new ones.

Cotool connects to the Splunk REST API with a Splunk authentication token. Every search runs as the Splunk user the token belongs to, so that user's roles decide which indexes Cotool can search.

## Create a Splunk token

**1. Open the tokens page**

In Splunk Web, click **Settings** > **Tokens**, then click **New
Token**. If the page says token authentication is not enabled, a Splunk
admin must turn it on first.

**2. Configure the token**

Set **User** to a dedicated Splunk user with search access to the
indexes Cotool needs. Do not use an admin account. Enter `Cotool` as the
**Audience**, and set an **Expiration**. If you leave the expiration
empty, the token expires after 30 days.

**3. Copy the token**

Click **Create** and copy the whole token. Splunk shows it only once.

## Connect in Cotool

1. Go to **Integrations** in the Cotool sidebar, open **Splunk**, and click **Connect**.
2. Enter your connection details:

| Field | Value |
| - | - |
| Splunk base URL | Your Splunk host with the management port, like `https://<your Splunk host>:8089`. The port is usually `8089`. |
| Authorization token | The token you created, without a `Bearer` or `Splunk` prefix |
| Query timeout | Optional. How long a search may run before Cotool finalizes it and returns partial results, from 1 to 10 minutes (default 2) |

3. Click **Connect**. Cotool starts building an [environment map](#environment-map) right away.

## Available Tools

When an agent has the Splunk integration enabled, it can use these tools:

| Tool | Description |
| - | - |
| `splunk_listDatasets` | List available indexes and sourcetypes |
| `splunk_describeSourceType` | Return exact field names, types, and examples for an index and, optionally, specific sourcetypes |
| `splunk_search` | Create an ad-hoc search job and return the first page of results |
| `splunk_paginateSearchResults` | Page through the results of a completed search job |
| `splunk_listDetections` | List saved searches (detections), across all apps or in one app |
| `splunk_createDetection` | Create a saved search (detection), with optional scheduling and alerting settings |
| `splunk_listApps` | List installed Splunk apps with their author, version, label, description, and state |

`splunk_createDetection` is the only tool that changes your Splunk configuration. The other tools read data and settings.

## How Cotool searches Splunk

* **Agents discover before they query.** Agents list indexes and sourcetypes, then check a sourcetype's fields, so their SPL uses real field names.
* **Searches name their indexes.** Cotool rejects searches over `index=*` and searches with leading wildcards such as `field=*value`, because both are slow on large deployments. Agents search concrete indexes and use `TERM()` for exact values such as IP addresses.
* **Searches have a time limit.** When a search reaches the query timeout you set, Cotool finalizes the job and returns the results found so far, to conserve Splunk resources.
* **Large results are paged.** A search returns its first page of results, and agents fetch the rest of a completed job page by page.
* **Cotool Logs come first.** If a log source is also ingested into Cotool Logs, agents query it there, and use Splunk for data only Splunk holds or when you ask for Splunk.

## Environment map

After you connect, and weekly after that, Cotool maps your Splunk environment: your indexes, the sourcetypes in each, their key fields, and sample rows. View the map on the Splunk integration page in Cotool. Agents use the map to choose where to search, and they can still discover data added since the last run.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.