@grepr/cli 1.11.5 → 1.11.6-48496dd

package/build/dist/docs-index/4481034e-4c12-4d54-885b-825293df0867.txt

@@ -0,0 +1,113 @@
+Process data in Grepr pipelines using built-in tools for parsing, filtering, enrichment, and transformation of log events.
+
+# Transform data in a Grepr pipeline
+
+A Grepr transform is a processing step that modifies, enriches, or restructures data as it flows through a pipeline. As records move through a pipeline, transforms allow you to parse structured and semi-structured data, filter records, and use a familiar SQL interface to perform more complex transformation of records as they move through a pipeline. Transforms are configured as pipeline steps that process data sequentially. Each transform receives input data, applies its logic, and passes the result to the next step in the pipeline.
+
+Most transforms are available in the Grepr pipelines UI. Some transforms are available only in the Grepr REST API or provide more capabilities when used with the API, such as [filters](#filter) and [branching the processing of records](#message-routing) based on query matches.
+
+The following sections describe the transforms available in Grepr pipelines.
+
+## Transform semi-structured records with the Grok parser \[#grok-parser]
+
+The Grok transform parses unstructured text using pattern matching with regular expressions and named capture groups. Use this transform to extract fields from log lines, error messages, and other text-based data where you need to identify specific patterns and convert them to structured fields.
+
+See [Grok parser](/transforms/grok).
+
+## Convert JSON messages into structured objects \[#json-parser]
+
+The JSON parser transforms JSON strings into structured JSON objects. This transform handles nested objects, arrays, and various data types, making it useful for processing API responses, configuration data, and structured log entries.
+
+See [Transform JSON strings into JSON objects](/transforms/json-parsing).
+
+## Restructure JSON objects with a remapper \[#remapper]
+
+The remapper transform moves or copies attributes to top-level fields or to tags in a JSON object. You can also use rename rules to move attribute values from one path to another within the same event. In the pipelines UI, a remapper with customizable default attributes is automatically added to a pipeline.
+
+See [Remap JSON attribute fields to top-level log event fields](/transforms/remapper).
+
+## Transform records with SQL \[#sql-transform]
+
+The SQL transform allows you to use ANSI standard SQL queries to filter, transform, and enrich data records. The SQL transform provides a familiar SQL interface to perform a number of data processing and transformation tasks.
+
+You can use the SQL transform in the Grepr UI or REST API. In the UI, the SQL transform is available when you configure filters.
+
+To learn about using the SQL transform in the Grepr API, see the [SQL Operation specification](/apis/api-spec#schema/SQLOperation).
+
+For a complete reference and examples, see [Transform events with SQL](/transforms/sql-transform).
+
+## Filter records based on conditions \[#filter]
+
+The Filter transform includes or excludes data records based on specified conditions. You can create filters using familiar query interfaces, such as SQL, as well as Datadog and New Relic log query-like syntaxes.
+
+In the Grepr pipelines UI, filters are located in predefined locations in the pipeline. To learn how to configure filters, see [Filter events in a Grepr pipeline](/transforms/filter-events).
+
+To have more flexibility for where filters are included in a pipeline, use the REST API. See [LogsFilter](/apis/api-spec#schema/LogsFilter).
+
+## Reduce log volumes with dynamic aggregation \[#reducer]
+
+The Grepr log reducer uses clustering algorithms to identify patterns in your log data and aggregate similar log messages. The output of this aggregation includes summaries and samples of similar messages. The log reducer is a core step in a log reduction pipeline, where it runs before processed log events are sent to your configured sinks. By sending summaries of similar messages rather than multiple events with redundant information, Grepr significantly reduces the volume of shipped logs and your observability costs. The log reduction pipeline also persists the complete set of raw logs to a low-cost data lake, enabling you to analyze and troubleshoot issues when necessary.
+
+To learn more about how Grepr reduces log volumes with dynamic aggregation, see [Reduce noise and improve the usability of your logs with the log reducer](/transforms/reducer).
+
+To learn how to create a log reduction pipeline, see [Tutorial: Build your first Grepr pipeline](/tutorials/first-pipeline).
+
+To learn how to use the resulting summarized log events in your observability platform along with raw logs stored in Grepr, see [Troubleshoot incidents with Grepr-processed data and your observability tool](/tutorials/troubleshooting-example).
+
+## Transform and enrich log messages with the REST API \[#log-transform-action]
+
+You can use the LogTransformAction in the REST API to specify actions that transform log messages, such as adding or removing attributes and tags. See [LogTransformAction](/apis/api-spec#schema/LogTransformAction).
+
+## Route the processing of messages based on query matches \[#message-routing]
+
+You can route log messages to be processed by different pipelines based on query matches. Because the pipelines UI doesn't support branching, Grepr recommends creating multiple pipelines that ingest data using the same source, and then use filters to route data to the correct pipeline.
+
+Sending logs to different destinations, rather than processing them differently, is a separate problem with its own approaches. See [_](/solution-guides/route-logs-to-several-accounts).
+
+You can also use the REST API to create more complex pipeline configurations. See [LogsBranch](/apis/api-spec#schema/LogsBranch).
+
+## Frequently Asked Questions
+
+### What transforms are available in Grepr pipelines?
+
+Grepr provides several transform types: Grok parser for parsing unstructured text with pattern matching, JSON parser for converting JSON strings into structured objects, remapper for restructuring JSON fields and attributes, SQL transform for complex filtering and enrichment using SQL queries, and Filter transform for conditional record processing. Most transforms are available in the UI, while some advanced options are available via REST API.
+
+### When should I use the Grok parser transform?
+
+Use the Grok parser when you need to extract structured data from unstructured text logs. It's ideal for parsing error messages, application logs, system logs, and other text-based data where you need to identify specific patterns and convert them into structured fields using regular expressions and named capture groups.
+
+### When should I use the JSON parser transform?
+
+Use the JSON parser when your log messages contain JSON strings that need to be converted into structured JSON objects. This is useful for processing API responses, configuration data, and structured log entries. The JSON parser handles nested objects, arrays, and various data types automatically.
+
+### What is the remapper transform and when is it used?
+
+The remapper transform moves or copies attributes to top-level fields or to tags in a JSON object. It's useful for standardizing log event structure by moving well-known fields like message, severity, and host from nested attributes to top-level fields. You can configure whether the source attribute is preserved or removed after remapping. The remapper also supports rename rules for moving attribute values from one path to another. The remapper is automatically added to pipelines in the UI with customizable default attributes.
+
+### When should I use the SQL transform?
+
+Use the SQL transform when you need complex filtering, transformation, or enrichment of log records. SQL provides a familiar interface for advanced operations like conditional logic, string manipulation, aggregations, and joining data. It's available in the UI for filters and via REST API for more flexibility.
+
+### Can I combine multiple transforms in a pipeline?
+
+Yes, transforms are configured as sequential pipeline steps. Each transform receives input from the previous step, applies its logic, and passes the result to the next step. This allows you to create complex data processing workflows by combining parsing (Grok), restructuring (remapper), and filtering/enrichment (SQL) transforms.
+
+### What is the Filter transform used for?
+
+The Filter transform includes or excludes data records based on specified conditions. You can use filters with SQL, Datadog, and New Relic-like query syntaxes. In the UI, filters are located in predefined pipeline positions, while the REST API provides more flexibility for filter placement.
+
+### Can I use the REST API for more advanced transform options?
+
+Yes, the REST API provides access to advanced transform options not available in the UI. For example, you can use LogTransformAction to add or remove attributes and tags, LogsBranch for complex message routing based on query matches, and more flexible filter placement. See the API specification for complete details on transform capabilities.
+
+### How do I choose between Grok and SQL transforms?
+
+Use Grok when you need pattern-based parsing of unstructured text to extract specific fields. Use SQL when you need complex conditional logic, calculations, string transformations, or filtering. Grok is specialized for text parsing, while SQL is more general-purpose for data manipulation and enrichment.
+
+### How does Grepr reduce log volumes and observability costs?
+
+Grepr uses clustering algorithms to identify patterns in log data and aggregates similar log messages. Instead of sending multiple redundant log events, Grepr sends summaries and samples of similar messages to your observability platform. This significantly reduces the volume of shipped logs while retaining the ability to analyze and troubleshoot issues. Raw logs are retained in a low-cost data lake for future reference.
+
+### What happens if a transform fails on a record?
+
+Transform behavior depends on the specific transform type and configuration. Parsing errors (like Grok or JSON parsing) typically skip records or add error attributes depending on your configuration. SQL transforms filter out records that don't match conditions. Review transform-specific documentation for error handling details.

package/build/dist/docs-index/4e2fc8e7-7301-437d-bb21-120742674de8.txt

@@ -0,0 +1,21 @@
+Guides that work through common Grepr situations end to end, showing the ways you can configure a pipeline to solve each one.
+
+# Solution guides
+
+A solution guide works through a situation you are likely to meet in production, rather than a single feature. A Grepr pipeline is a free-form processing graph, so most situations have more than one good shape. Each guide states the problem, then walks through the ways you can configure Grepr for it.
+
+Use these guides when you know what you want to achieve but not yet how to shape your pipelines around it. To learn a feature on its own, see the reference documentation for [pipelines](/pipelines), [transforms](/transforms), and [integrations](/integrations). To work through the product step by step, see [_](/tutorials).
+
+## Route logs to several vendor accounts
+
+Your logs belong to more than one account in your observability platform, because separate teams, environments, or business units each own their own. This guide shows two ways to get each log, and each summary of those logs, to the account that owns it: a pipeline for each group, or one pipeline whose reducer groups on a routing key and whose sinks each filter on it. See [_](/solution-guides/route-logs-to-several-accounts).
+
+## Frequently Asked Questions
+
+### What is a Grepr solution guide?
+
+A solution guide works through a situation you are likely to meet in production rather than a single feature. A Grepr pipeline is a free-form processing graph, so most situations have more than one good shape. Each guide states the problem, then walks through the ways you can configure Grepr for it.
+
+### How is a solution guide different from a tutorial?
+
+A tutorial teaches the product step by step, starting from nothing. A solution guide assumes you know what you want to achieve and shows you the ways you can shape your pipelines around it.

package/build/dist/docs-index/4eb68cc0-ddf9-4eff-94ab-3efa5becab4d.txt

@@ -0,0 +1,145 @@
+Create a Grepr Agent integration so any system that can send JSON over HTTP starts an AI agent investigation for each event it reports.
+
+# Send events to an AI agent with a Grepr Agent integration
+
+A Grepr Agent integration is a webhook endpoint that turns events from another system into AI agent investigations. Any system that can send a JSON body over HTTP can use it, such as an alerting platform, a Kubernetes event forwarder, or a script of your own. Each accepted event starts an investigation on every agent subscribed to the integration.
+
+The integration carries a description of the payload you send. The agent reads that description alongside every event, which is what lets one agent make sense of alerts from several different systems without you writing a parser for each.
+
+> Grepr Agent integrations, along with the rest of the Grepr AI agent features, are in a closed beta. To request access, contact <support@grepr.ai>.
+
+## Requirements
+
+To send events to an agent, you need:
+
+* A Grepr API key, which you generate on the **Developer** page. See [Authenticate your requests](#authentication).
+* At least one AI agent to subscribe to the integration. See [_](/ai-agents/create-an-agent).
+
+## Create a Grepr Agent integration \[#create]
+
+1. On the **Integrations** page, next to the **Grepr Agent** section heading, click **Add new**.
+
+2. In the **Add Grepr Agent** dialog, complete the following fields:
+
+   \| Field | Description | |---|---| | **Name** | A name for the integration, used to identify it when you subscribe an agent. | | **System type** | A short label for the sending system, such as `datadog-monitors` or `k8s-events`. The agent sees this label with every event. | | **Schema description** | An explanation of the payload's structure and the meaning of its fields. The agent reads this with every event from this source. |
+
+3. Click **Create**.
+
+Grepr then shows the ingest URL for the integration, which is where you send your events.
+
+### Write a schema description the agent can use \[#schema-description]
+
+The schema description is the only thing that tells the agent what the fields in your payload mean, so it decides how well the agent can reason about your events. An annotated example payload works better than prose, because it shows the structure and the meaning together:
+
+```text
+An alert from your Datadog monitors. Fields:
+{
+  "alert_id": "abc123",          // stable id for the monitor
+  "alert_title": "5xx rate high on checkout",
+  "priority": "P2",              // P1 is highest, P5 is lowest
+  "service": "checkout",         // the owning service, matches the service tag in your logs
+  "env": "prod",                 // prod, staging, or dev
+  "runbook": "https://wiki.example.com/runbooks/checkout-5xx",
+  "triggered_at": "2026-09-21T14:03:00Z"
+}
+```
+
+Describe the fields an agent would need to act: which field identifies the affected service, which indicates severity, and which values are expected in each. A description can be up to 16,384 characters.
+
+To change a description later, click the three-dot menu on the integration card, select **Edit**, and update the **Schema description** field. The next event the integration receives uses the new description.
+
+## Authenticate your requests \[#authentication]
+
+Requests to the ingest URL authenticate with a Grepr API key sent in the `GREPR-API-KEY` header. Grepr identifies your organization from the key and the integration from the URL, so the sender does not supply either.
+
+To generate a key, go to the **Developer** page, select **API Keys**, and under **External Triggers API Key**, click **Generate**. Copy the key when it appears and store it in your sending system's secret store.
+
+## Send an event \[#send]
+
+To find the ingest URL, on the integration card, click **Setup**. The URL has the following form, where `<integration-id>` identifies the integration you created:
+
+```bash
+https://<your-org>.app.grepr.ai/api/v1/integrations/webhooks/<integration-id>/events
+```
+
+Send the event as the request body. The body is your payload, with no Grepr envelope around it:
+
+```bash
+curl -X POST \
+  "https://<your-org>.app.grepr.ai/api/v1/integrations/webhooks/<integration-id>/events" \
+  -H "GREPR-API-KEY: <your-api-key>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "alert_id": "abc123",
+    "alert_title": "5xx rate high on checkout",
+    "priority": "P2",
+    "service": "checkout",
+    "env": "prod"
+  }'
+```
+
+Grepr returns `202 Accepted` after it submits the event to every subscribed agent without a failure. The responses are:
+
+| Status | Meaning |
+| --- | --- |
+| `202` | The event was submitted to every subscribed agent. The body lists the investigation identifiers. |
+| `400` | The body is not valid JSON. |
+| `401` | The API key is missing or not valid. |
+| `404` | No integration matches the id in the URL. |
+| `409` | The integration has no agent that can be started. Subscribe an agent. |
+| `413` | The body is larger than the 262,144 character limit. |
+| `503` | At least one agent could not be started, for a reason that might not persist. |
+
+A `202` can still include agents that were not investigated. An agent at its concurrency limit with a queueing policy of discard drops the event deliberately, which is a decision rather than a failure, so the event is not resubmitted.
+
+Subscribe an agent before you point a production system at the URL. An integration with no subscribed agents rejects every event with `409` rather than accepting it and doing nothing.
+
+### Retry safely \[#retries]
+
+Retry on `503` and nothing else. A `503` means at least one agent could not be started, so the event is lost for that agent if you drop it.
+
+Retrying a `503` can also duplicate work, because a `503` is returned even when some of the subscribed agents did start. Those agents are submitted again on the retry, and Grepr does not deduplicate events. There is no response that distinguishes the two cases, so weigh losing an event against investigating it twice, and prefer retrying when the agent's conclusions are cheap to read and the event matters.
+
+To clear duplicates, cancel them in bulk from the agent's **Investigations** step. See [_](/ai-agents/investigations#end-for-good).
+
+## Subscribe an agent \[#subscribe]
+
+An integration on its own does nothing. To have an agent investigate the events it receives, subscribe that agent to the integration from the agent's **Subscriptions** step. To learn more, see [_](/ai-agents/subscriptions#webhook-sources).
+
+## Grant team access \[#team-access]
+
+When you have teams in your Grepr organization, you can grant access to the integration to one or more of those teams. To configure team access when you create or edit an integration:
+
+1. In the **Grant Team Access** section, click the plus sign icon (+).
+
+2. Select the team or teams that should be granted access to the integration.
+
+3. Click **Create**.
+
+To learn more, see [Manage teams in the Grepr platform](/admin/manage-teams) and [Permissions in the Grepr platform](/grepr-platform/permissions).
+
+## Frequently Asked Questions
+
+### What is a Grepr Agent integration?
+
+A Grepr Agent integration is a webhook endpoint that turns events from another system into AI agent investigations. Any system that can send a JSON body over HTTP can use it. Each accepted event starts an investigation on every agent subscribed to the integration.
+
+### How do I authenticate requests to a Grepr Agent webhook?
+
+Send a Grepr API key in the GREPR-API-KEY header. Generate the key on the Developer page under API Keys, in the External Triggers API Key section. Grepr identifies your organization from the key and the integration from the URL.
+
+### Why does the schema description matter?
+
+The agent reads the schema description alongside every event from that integration, and it is the only thing that tells the agent what your payload's fields mean. An annotated example payload works best, because it shows the structure and the meaning of each field together.
+
+### How large can a webhook event be?
+
+The request body is limited to 262,144 characters. A larger body is rejected with a 413 response.
+
+### Why does my Grepr Agent webhook return 409?
+
+The integration has no agent that can be started, which normally means no agent is subscribed to it. Subscribe an agent on that agent's Subscriptions step. Grepr returns 409 rather than accepting the event and silently doing nothing.
+
+### Can a webhook retry start duplicate investigations?
+
+Yes. A 503 is returned when at least one agent could not be started, even if others did start, and Grepr does not deduplicate events. Retrying that 503 resubmits the agents that already succeeded. Retry on 503 anyway when the event matters, because dropping it loses the event for the agent that failed, and cancel any duplicates in bulk from the agent's Investigations step.

package/build/dist/docs-index/524d667f-7671-4b39-bb72-de87c87a6ba9.txt

@@ -0,0 +1,59 @@
+# ReadOrgConstraints
+
+**Type**: `object`
+
+## Properties
+
+- name: maxAnthropicIntegrations (optional)
+  type: integer
+
+- name: maxDataWarehouseIntegrations (optional)
+  type: integer
+
+- name: maxDatadogApiKeysPerIntegration (optional)
+  type: integer
+
+- name: maxDatadogIntegrations (optional)
+  type: integer
+
+- name: maxGeminiIntegrations (optional)
+  type: integer
+
+- name: maxLiteLlmIntegrations (optional)
+  type: integer
+
+- name: maxMcpIntegrations (optional)
+  type: integer
+
+- name: maxNewRelicIntegrations (optional)
+  type: integer
+
+- name: maxOpenAiIntegrations (optional)
+  type: integer
+
+- name: maxOtlpIntegrations (optional)
+  type: integer
+
+- name: maxPipelines (optional)
+  type: integer
+
+- name: maxPromotedAttributeColumns (optional)
+  type: integer
+
+- name: maxPromotedTagColumns (optional)
+  type: integer
+
+- name: maxPromotionPolicyEntriesPerList (optional)
+  type: integer
+
+- name: maxS3DataWarehouseIntegrations (optional)
+  type: integer
+
+- name: maxS3VectorIndexIntegrations (optional)
+  type: integer
+
+- name: maxSplunkIntegrations (optional)
+  type: integer
+
+- name: maxSumoIntegrations (optional)
+  type: integer

package/build/dist/docs-index/5261fa91-0e4b-4528-b19b-872260c61f79.txt

@@ -0,0 +1,33 @@
+# Get vendor estimation results for a run
+
+**GET** `/v1/integrations/{integrationId}/exceptions/vendor-estimation-runs/{runId}/results`
+
+**Operation ID**: `getVendorEstimationRunResults`
+**Summary**: Get vendor estimation results for a run
+Returns the run's per-exception estimates keyed by composite exception id. Each is counted, pending, unparseable or an error, selected by its type field. An exception missing from the response was not in this run.
+
+## Tags
+- Integration Exceptions
+## Parameters
+
+- **integrationId** (required) - path
+  - Integration id
+  - Type: string
+- **runId** (required) - path
+  - Run id
+  - Type: string
+
+## Responses
+
+### 200
+
+Results retrieved
+
+- **Content-Type**: `application/json` / object
+### 401
+
+Unauthorized
+
+### 404
+
+Not Found - Integration or run not found.

package/build/dist/docs-index/5816e667-3426-490c-ac15-c87ef594f637.txt

@@ -0,0 +1,43 @@
+# Replace a dataset table promotion policy
+
+**PUT** `/v1/datasets/{id}/tables/{tableKey}/promotion`
+
+**Operation ID**: `putTablePromotion`
+**Summary**: Replace a dataset table promotion policy
+Validates and stores the complete promotion policy on the table. Newly included tag columns are added synchronously before the request returns, in the same commit as the policy. Send back the revision the policy was read at to be refused rather than overwrite a change made since; omit it to replace whatever is stored.
+
+## Tags
+- Datasets
+## Parameters
+
+- **id** (required) - path
+  - Type: string
+- **tableKey** (required) - path
+  - Type: string
+
+## Request Body
+
+The complete promotion policy document. It is decoded by the same strict codec that reads the stored policy: every field is typed exactly, no unknown field is accepted at any depth, and no value is coerced. It replaces the stored policy rather than patching it, and both groups are required -- a body that omits "tags" or "attributes" is rejected, not read as a request to stop discovery for that group. The cap is the switch: send a group with "cap": 0 to stop it promoting fields it has not seen before. That does not blank the group -- the columns the table already carries keep being written, and a path is stopped by naming it in that group's exclude list. Read the current policy and send it back whole, changing only what you mean to change.
+
+**Content-Type**: `application/json`
+
+**Schema**: `PromotionPolicy`
+
+## Responses
+
+### 200
+
+The persisted promotion policy.
+
+- **Content-Type**: `application/json` / `PromotionPolicy`
+### 400
+
+Invalid promotion policy.
+
+### 404
+
+Dataset or table not found.
+
+### 409
+
+The policy changed since the revision the request was made against; read it again and reapply the change. Or the table kept changing under the request, which a running writer's own evolution can cause; retry.

package/build/dist/docs-index/5b413cd2-f5d9-4a0e-8e50-ba5672ef476d.txt

@@ -0,0 +1,21 @@
+# query
+
+**POST** `/v1/metrics/query`
+
+**Operation ID**: `query`
+**Summary**: No summary provided.
+## Tags
+- Status Metrics
+## Request Body
+
+**Content-Type**: `application/x-www-form-urlencoded`
+
+**Schema**: object
+
+## Responses
+
+### default
+
+default response
+
+- **Content-Type**: `application/json` / `QueryResult`

package/build/dist/docs-index/5c1a9e25-2cb5-4ead-bb3f-7262ab75cf4e.txt

@@ -0,0 +1,19 @@
+# CheckAppKeyScopesRequest
+
+Keys and site to check Datadog authorization scopes against
+
+**Type**: `object`
+
+## Properties
+
+- name: apiKey (required)
+  type: string
+  description: API key to authenticate the probes with
+
+- name: appKey (required)
+  type: string
+  description: Application key to check
+
+- name: site (required)
+  type: string
+  description: The Datadog site to probe

package/build/dist/docs-index/5edbd083-96af-46da-8fd1-4e51ed7561c8.txt

@@ -0,0 +1,171 @@
+Start, follow, and read Grepr AI agent investigations, guide a running one, understand each state, and review the pipeline changes an agent proposes.
+
+# Run and review investigations
+
+An *investigation* is one run of an agent. It holds the signals that triggered it, every turn the agent took, every tool it called, the changes it made outside the sandbox that Grepr recognizes, and the summary it finished with. Investigations are listed on the agent's **Investigations** step.
+
+An investigation is a record, not a conversation. You can interrupt one to add guidance, but most investigations run to completion unattended and you read them afterwards.
+
+## Start an investigation manually \[#start-manual]
+
+Start one manually to try out an agent before subscribing it to anything, or to point an agent at something you already know about.
+
+1. On the agent's page, click **Run investigation**.
+2. Optionally enter **Context**, which is what the agent starts from, such as the service to look at or the symptom you saw.
+3. Click **Start investigation**.
+
+Context is the only instruction an investigation started manually receives beyond the agent's system prompt, so include the service, the time range, and the symptom. An investigation with no context relies entirely on the agent's prompt to decide what to examine.
+
+An investigation you start manually is not subject to the maximum queue wait, but it is subject to the concurrency limit and the token budgets. When a budget is exhausted, a manual investigation is discarded rather than queued, so you find out immediately instead of waiting. See [_](/ai-agents/create-an-agent#limits).
+
+## Investigation states \[#states]
+
+| State | What it means | What you can do |
+| --- | --- | --- |
+| Queued | Accepted and waiting for a free slot on the agent. No sandbox exists yet. | Cancel it. |
+| Running | The agent is working. | Stop it or cancel it. |
+| Stopping | A stop was requested and is being applied. | Cancel it. |
+| Cancelling | A cancel was requested and is being applied. | Wait for it to finish. |
+| Stopped | Either paused and waiting for instruction, or ended after waiting too long. | Resume a paused one, or continue a finished one in a new investigation. |
+| Completed | The agent finished and wrote a summary. | Continue it in a new investigation. |
+| Failed | The investigation ended with an error. | Read the reason, then continue it in a new investigation. |
+| Cancelled | You cancelled it. | Continue it in a new investigation. |
+| Discarded | Recorded but never ran. | Read why, then address the cause. |
+
+Stopped covers two situations, and the status icon tells them apart. A stopped investigation that is still waiting for instruction is paused and can be resumed, carrying on from where it left off while its sandbox is still there. If the sandbox is lost while the investigation is paused, the resumed agent restarts from the triggering signals and whatever you resume it with, so give it what it needs rather than assuming it still remembers. One that waited too long without instruction has ended, and the work it did is readable but no longer resumable. So resume a stopped investigation while you still want its context, rather than leaving it paused indefinitely.
+
+Completed, Failed, Cancelled, Discarded, and a timed-out Stopped are final. Nothing restarts them, though you can start a fresh investigation seeded with what one learned. See [Continue in a new investigation](#continue).
+
+## Read an investigation \[#read]
+
+Open an investigation from the agent's **Investigations** step. It reads top to bottom: what the agent concluded, what set it off, then how it got there.
+
+### The summary \[#summary]
+
+A finished investigation opens with the agent's own account of what it found. An investigation that failed or was discarded carries the reason it ended instead of a conclusion, which is the first thing to read when a run did not work.
+
+The summary is what the agent wrote for you to read, so it is the part to read when you want the conclusion. Read the timeline when you want to check the conclusion.
+
+### The triggering signal \[#trigger]
+
+The triggering signal is the event that started the run. A webhook signal shows the payload the sending system posted. A log pattern signal shows the pattern the reducer detected and a sample log line that matched it. An investigation you started manually shows the context you typed.
+
+Read the signal when a conclusion surprises you. An agent reasoning from a payload whose fields it cannot interpret often produces a plausible but wrong summary, and the fix is usually the integration's schema description rather than the agent's prompt. See [_](/integrations/grepr-agent-webhooks#schema-description).
+
+### The timeline \[#timeline]
+
+The timeline is every step in order: what the agent was told, what it said, each tool it called with the arguments it passed, and what each tool returned. Tool output is collapsed, so you can scan the shape of a run and expand only the calls that matter. Each call reports how long it took.
+
+Read the timeline to answer why an agent concluded what it did. Two patterns are worth recognizing:
+
+* Repeated similar tool calls usually mean the agent is missing a capability or some knowledge, and is working around the gap. Consider enabling a skill that covers the task or using a better model.
+* A run that ends without a conclusion usually means it reached its turn or token limit. The last turn shows where it was.
+
+### Recorded actions \[#actions]
+
+An *action* is a consequential change the agent made outside its own sandbox: a pipeline version it applied, a pipeline change it proposed for review, or a write it made through a connected MCP integration. Reads are not actions, and neither is everything an agent can do from a shell, so treat the count as a record of the changes Grepr recognizes rather than a complete audit. Actions appear beneath the tool call that made them and are counted in the **Actions** column of the list, so you can find the investigations that changed something without reading any transcripts.
+
+Actions record successful changes, not attempts. A tool call that failed appears in the timeline but produces no action.
+
+## Guide a running investigation \[#guide]
+
+### Stop and resume \[#stop-resume]
+
+Stopping ends the agent's session and pauses the investigation. Work already in flight is abandoned rather than finished, so a tool call that was running might not complete. Everything the investigation had recorded up to that point is kept, which is what a resume continues from.
+
+To continue it, click **Resume**. You can add a message to steer it, such as naming the service it should focus on, or resume with no message to let it carry on. Stop and resume when an agent is heading the wrong way but its work so far is worth keeping.
+
+### Cancel \[#end-for-good]
+
+Cancelling ends an investigation for good. Use it when the run is not worth finishing. The transcript remains readable.
+
+To cancel several at once, select them in the list and cancel the selection. This is how you clear a backlog that built up, such as from a misconfigured source. Cancelling is permanent, and an investigation that has already finished is left alone.
+
+### Continue in a new investigation \[#continue]
+
+A finished investigation cannot be resumed, but you can start a new one seeded from it. The new investigation begins with the earlier conversation, and you can add a message to direct it, such as asking it to verify that a change worked.
+
+The seed carries what the agent and you said to each other, not the tool calls it made or the results they returned, and a long conversation is trimmed to its most recent part. Put anything the new investigation must not lose into the message you start it with.
+
+Use this to carry an investigation forward after you have acted on it, rather than starting from nothing and paying for the same discovery twice.
+
+## Find investigations \[#find]
+
+The list holds one row per investigation, with its identifier, what triggered it, its summary, when it was created, how long it ran and how long it waited in the queue, its state, and how many actions it recorded.
+
+Three filters narrow it:
+
+* **Status** limits the list to the states you select.
+* **Actions** separates investigations that recorded a change from those that did not.
+* **Trigger** limits the list to investigations started manually, by a webhook, or by a log pattern.
+
+Filter on recorded actions when you want to review what an agent has changed, and on failed status when you are diagnosing an agent that is not working.
+
+## Why an investigation was discarded \[#discarded]
+
+A discarded investigation was recorded but never ran. There are three reasons, and each has a different fix:
+
+| Reason | What to do |
+| --- | --- |
+| The agent was at its concurrency limit and set to discard extra signals. | Raise the concurrency limit, switch to queueing, or reduce what the source emits. |
+| A queued investigation waited longer than the maximum queue wait. | Raise or remove the maximum queue wait, or raise the concurrency limit so the queue drains faster. |
+| A token budget was exhausted. | Raise the budget that blocked it, or wait for the window to reset. Check which budget it was on the agent's page. |
+
+A rise in discarded investigations usually means a source is emitting more than the agent can handle. Reducing what the source emits keeps the signal you want, whereas raising the limits keeps the volume and increases the cost. See [_](/ai-agents/subscriptions#volume).
+
+## Review the pipeline changes an agent proposes \[#suggestions]
+
+An agent set to require human approval records each pipeline change it proposes as a *suggestion* on that pipeline, and changes nothing until you apply it. Suggestions are on the pipeline's **Suggestions** step, not on the agent, because the decision is about the pipeline.
+
+Each suggestion lists when it was proposed, what it changes, and the investigation that produced it. To decide, review the proposed change as a difference against the pipeline's configuration, and read the investigation that produced it to see the evidence the agent based it on.
+
+Then either apply it or reject it:
+
+* Applying re-verifies the change against the pipeline's configuration as it is now, not as it was when the agent proposed it, and a running pipeline then restarts to pick it up. A suggestion whose assumptions no longer hold is refused rather than applied blindly, and it stays pending, so you can retry it after the pipeline settles.
+* Rejecting leaves the pipeline untouched and closes the suggestion.
+
+Reviewing a suggestion changes nothing on the live pipeline, so read as many as you like before deciding. Suggestions do not expire, but an old one is more likely to be refused on apply, because the pipeline's configuration has likely drifted. Review them while they still match the pipeline.
+
+To let an agent apply its own changes instead, see [_](/ai-agents/capabilities#change-approval).
+
+## Read investigations from the CLI \[#cli]
+
+The Grepr CLI reads investigations, which is useful for auditing many runs at once or feeding them into your own tooling.
+
+```bash
+# List an agent's failed investigations
+grepr investigation:list --agent-id <agent-id> --status FAILED --page-size 10
+
+# Read one investigation's metadata, summary, and recorded actions
+grepr investigation:get <investigation-id>
+
+# Read the turns, including tool calls and their results
+grepr investigation:turns <investigation-id> --page-size 10
+
+# Export a transcript to a file
+grepr investigation:transcript <investigation-id> --all --output investigation.json
+```
+
+To follow a running investigation as it progresses, add `--follow` to `investigation:turns`. To learn more about the CLI, see [_](/cli).
+
+## Frequently Asked Questions
+
+### How do I start a Grepr AI agent investigation manually?
+
+On the agent's page, click Run investigation, optionally enter the context the agent should start from, and click Start investigation. Context is the only instruction beyond the agent's system prompt, so include the service, the time range, and the symptom.
+
+### What does a stopped investigation mean in Grepr?
+
+Stopped covers two situations. An investigation that is still waiting for instruction is paused and can be resumed, carrying on from where it left off while its sandbox is still there. If the sandbox is lost while it is paused, the resumed agent restarts from the triggering signals and the message you resume it with. One that waited too long without instruction has ended, and remains readable but is no longer resumable. The status icon tells the two apart.
+
+### Can I resume a completed Grepr AI agent investigation?
+
+No. Completed, failed, cancelled, discarded, and timed-out stopped investigations are final. You can start a new investigation seeded from the finished one, and add a message to direct it, such as asking it to verify that a change worked.
+
+### Why was my investigation discarded?
+
+There are three reasons: the agent was at its concurrency limit and set to discard extra signals, a queued investigation waited longer than the maximum queue wait, or a token budget was exhausted. The agent's page reports which token budget blocked it and when the window resets.
+
+### How do I review a pipeline change proposed by a Grepr AI agent?
+
+Suggestions appear on the pipeline's Suggestions step. Review the proposed change as a difference against the current configuration and read the investigation that produced it, then apply or reject it. Applying re-verifies the change against the pipeline as it is now, and a running pipeline restarts to pick it up. A suggestion that no longer verifies is refused and stays pending, leaving the pipeline untouched.