Skip to main content
skill CX Codex

openobserve-api — Claude Code skill: what it does, how to install

openobserve-api — a skill that drives OpenObserve over its REST API: searches, streams, dashboards and panels. Useful when an agent has to pull data from a Cloud or self-hosted instance.

Apache-2.0 ★ 1,216 updated 2026-10-24

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install openobserve-skills@claude-settings
Open on GitHub

What openobserve-api does

The agent sends curl requests to https://<host>/api/<org> and logs in with an email and password pair through basic auth. OpenObserve ships no first-party CLI, so every call is plain HTTP. A search is a POST to _search carrying SQL in the DataFusion dialect, with start_time and end_time in microseconds and a search_type that decides the rate-limit and audit bucket. Metrics can go through PromQL instead.

Dashboards get the full set: list, read, create, update, delete, plus a move between folders, all under ?folder=. An update carries the current hash, so a 409 Conflict means someone changed the dashboard first and you refetch before retrying. What you send back is the inner v8 object, not the wrapper the server returned. Single-panel add, edit and delete exist only for v8 and each one hands back a new hash.

Request shapes are checked against the docs repo and the server source via gh api, and the handler wins when the two disagree. That step needs gh installed and authenticated. Time is the other tripwire: leave out start_time and end_time and the query scans the whole stream.

What it helps with

  • pull logs out of a self-hosted OpenObserve instance with SQL
  • turn a v8 dashboard JSON file into a live dashboard
  • edit one panel without rewriting the whole dashboard
  • read a stream schema before writing queries
  • move a dashboard into another folder

Example prompts for the agent

  • Query OpenObserve: count events per host_name in "my_stream" over the last hour
  • Create a dashboard in folder default from dashboard-v8.json
  • Add a panel to dashboard <dashboard_id> using a fresh hash

How to install openobserve-api

1Plugin marketplace

/plugin marketplace add fcakyon/claude-codex-settings
/plugin install openobserve-skills@claude-settings

This installs the whole openobserve-skills plugin with all its skills

2Skills CLI (Vercel)

npx skills add fcakyon/claude-codex-settings --skill openobserve-api -a claude-code

3Manually: put the files in place

~/.claude/skills/openobserve-api/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/openobserve-api/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about openobserve-api

How do I install openobserve-api in Claude Code?

Use the plugin marketplace: /plugin marketplace add fcakyon/claude-codex-settings first, then /plugin install openobserve-skills@claude-settings.

What does openobserve-api do?

It gives the agent working recipes for the OpenObserve REST API: running searches and SQL, listing streams with their schemas, and managing dashboards and their panels.

Does it work with a self-hosted instance?

Yes. Point the base URL at your own host and keep the /api/<org> path; auth stays basic with email and password, either through curl -u or a base64-encoded Authorization header.

Source text

SKILL.md · Apache-2.0
---
name: openobserve-api
description: This skill should be used when user asks to "query OpenObserve", "create OpenObserve dashboard", "edit OpenObserve panel", "fetch OpenObserve logs", "run OpenObserve search", "list OpenObserve streams", "ingest into OpenObserve", or works with OpenObserve Cloud / self-hosted via REST API. Covers auth, search/SQL, streams, dashboards (CRUD + per-panel ops), the v8 panel JSON schema, and known pitfalls (re-aggregation, hash concurrency, microsecond timestamps).
license: Apache-2.0
---

# OpenObserve REST API Skill

Programmatic OpenObserve usage for AI agents. Talk to any OpenObserve instance (Cloud or self-hosted) using `curl` and the documented REST API. No CLI required — there is no first-party OpenObserve CLI.

## Retrieval First

Your knowledge of OpenObserve API shapes may be outdated. **Prefer retrieval over pre-training**:

| Source        | How to retrieve                                                                                                     | Use for                                    |
| ------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| Docs repo     | `gh api repos/openobserve/openobserve-docs/contents/docs/reference/api/{path}.md -q .content \| base64 -d`          | Authoritative request/response samples     |
| Server source | `gh api repos/openobserve/openobserve/contents/src/handler/http/request/dashboards/mod.rs -q .content \| base64 -d` | Endpoint paths, query params, status codes |
| Panel schema  | `gh api repos/openobserve/openobserve/contents/src/config/src/meta/dashboards/v8/mod.rs -q .content \| base64 -d`   | Exact panel JSON structure (Rust structs)  |

When docs and server source disagree, **trust the server source** — handlers ship faster than docs.

## 1. Auth

HTTPS basic auth with email + password. There is no token endpoint.

```bash
# Method 1: curl -u shorthand
curl -u "[email protected]:PASSWORD" "https://eu1.openobserve.ai/api/<org>/streams"

# Method 2: explicit header
TOKEN=$(printf '%s' "[email protected]:PASSWORD" | base64)
curl -H "Authorization: Basic $TOKEN" "https://eu1.openobserve.ai/api/<org>/streams"
```

Endpoints below assume `BASE=https://<host>/api/<org>` and `AUTH="-u [email protected]:PASSWORD"`.

## 2. Search / Query — `POST $BASE/_search`

Optional query string `?type=logs|metrics|traces` (default `logs`).

```bash
curl $AUTH -H 'Content-Type: application/json' \
  "$BASE/_search?type=logs" \
  -d '{
    "query": {
      "sql": "SELECT host_name, COUNT(*) AS n FROM \"my_stream\" GROUP BY host_name ORDER BY n DESC",
      "start_time": 1777000000000000,
      "end_time":   1777999999000000,
      "from": 0,
      "size": 100
    },
    "search_type": "ui"
  }'
```

- **Timestamps are microseconds** (Unix epoch × 1_000_000). Always set `start_time`/`end_time` — missing them scans everything.
- `search_type` ∈ `ui | dashboards | reports | alerts` — affects rate limits and audit logs.
- Pagination: `from` (offset) + `size` (limit, max ~10000 per request).
- Response: `{ took, hits[], total, from, size, scan_size }`.
- SQL flavor: DataFusion / Arrow SQL. Identifiers in double quotes (`"stream_name"`), strings in single quotes (`'value'`).
- Time-bucketed group by: `SELECT histogram(_timestamp, '5 minute') AS ts, COUNT(*) FROM "stream" GROUP BY ts ORDER BY ts`.
- Term aggregation: `SELECT k8s_namespace, COUNT(*) FROM "stream" GROUP BY k8s_namespace`.
- Full-text: `match_all('text')`, `str_match(field, 'text')`. Default full-text fields: `log, message, msg, content, data, json`.
- PromQL on metrics: `POST $BASE/prometheus/api/v1/query_range`.
- Trace context window: `GET $BASE/{stream}/_around?key=<ts_us>&size=N`.

## 3. Streams — `GET $BASE/streams`

```bash
# List
curl $AUTH "$BASE/streams?fetchSchema=false&type=logs"

# Schema
curl $AUTH "$BASE/streams/<stream>/schema?type=logs"

# Update settings
curl $AUTH -X PUT -H 'Content-Type: application/json' "$BASE/streams/<stream>/settings" -d '{"partition_keys":["host_name"]}'

# Delete
curl $AUTH -X DELETE "$BASE/streams/<stream>?type=logs"
```

Field types: `Utf8 | Int64 | Float64 | Timestamp | Boolean`. Timestamp field is always `_timestamp` (microseconds).

## 4. Dashboards — `GET|POST|PUT|DELETE $BASE/dashboards`

All take `?folder=<folder_id>` (default `default`).

```bash
# List
curl $AUTH "$BASE/dashboards?folder=default"

# Get one (returns versioned wrapper {v1..v8, version, hash, updatedAt})
curl $AUTH "$BASE/dashboards/<dashboard_id>?folder=default"

# Create — body is the UNWRAPPED inner v8 object
curl $AUTH -X POST -H 'Content-Type: application/json' \
  "$BASE/dashboards?folder=default" \
  -d @dashboard-v8.json

# Update — REQUIRES the current hash for optimistic concurrency
HASH=$(curl -s $AUTH "$BASE/dashboards/<id>?folder=default" | jq -r .hash)
curl $AUTH -X PUT -H 'Content-Type: application/json' \
  "$BASE/dashboards/<id>?folder=default&hash=$HASH" \
  -d @updated-dashboard.json

# Delete
curl $AUTH -X DELETE "$BASE/dashboards/<id>?folder=default"

# Move between folders
curl $AUTH -X PUT -H 'Content-Type: application/json' \
  "$BASE/folders/dashboards/<id>" \
  -d '{"from":"default","to":"<target_folder_id>"}'
```

**Critical: PUT/POST body must be the unwrapped inner v8 object**, not the full `{v1..v8, version, hash}` wrapper. The server returns the wrapper but expects you to send only the inner object back.

```bash
# Read, mutate, write — the correct pattern
RAW=$(curl -s $AUTH "$BASE/dashboards/<id>?folder=default")
HASH=$(echo "$RAW" | jq -r .hash)
echo "$RAW" | jq '.v8 | .title = "New Title"' \
  | curl -s $AUTH -X PUT -H 'Content-Type: application/json' \
    "$BASE/dashboards/<id>?folder=default&hash=$HASH" -d @-
```

A `409 Conflict` response means the hash is stale — refetch and retry.

### Per-panel operations (v8 only — return new hash)

```bash
# Add panel
curl $AUTH -X POST -H 'Content-Type: application/json' \
  "$BASE/dashboards/<id>/panels?folder=default&hash=$HASH" \
  -d '{"panel": {...}, "tabId": "default"}'

# Update panel
curl $AUTH -X PUT -H 'Content-Type: application/json' \
  "$BASE/dashboards/<id>/panels/<panel_id>?folder=default&hash=$HASH" \
  -d '{...panel...}'

# Delete panel
curl $AUTH -X DELETE \
  "$BASE/dashboards/<id>/panels/<panel_id>?folder=default&hash=$HASH&tabId=default"
```

## 5. Panel JSON (v8)

The dashboard tree: `dashboard.tabs[].panels[]`. Each panel:

```json
{
  "id": "panel-1",
  "type": "table",
  "title": "Per-host stats",
  "description": "",
  "queryType": "sql",
  "queries": [
    {
      "query": "SELECT host_name, COUNT(*) AS n FROM \"my_stream\" GROUP BY host_name ORDER BY n DESC",
      "vrlFunctionQuery": "",
      "customQuery": true,
      "fields": {
        "stream": "my_stream",
        "stream_type": "logs",
        "x": [
          { "label": "Host", "alias": "host_name", "column": "host_name", "color": null, "aggregationFunction": null }
        ],
        "y": [
          {
            "label": "Count",
            "alias": "n",
            "column": "n",
            "color": null,
            "aggregationFunction": null,
            "treatAsNonTimeseries": true
          }
        ],
        "z": [],
        "breakdown": [],
        "filter": { "filterType": "group", "logicalOperator": "AND", "conditions": [] }
      },
      "config": { "promql_legend": "", "layer_type": "scatter", "weight_fixed": 1, "limit": 0, "min": 0, "max": 100 }
    }
  ],
  "config": {
    "show_legends": true,
    "decimals": 2,
    "unit": "currency",
    "unit_custom": "USD"
  },
  "layout": { "x": 0, "y": 0, "w": 48, "h": 14, "i": 1 }
}
```

### Panel `type` values

`metric` (single big number) · `table` · `bar` · `h-bar` · `stacked` · `h-stacked` · `line` · `area` · `area-stacked` · `scatter` · `pie` · `donut` · `heatmap` · `gauge` · `geomap` · `maps` · `sankey` · `html` · `markdown`.

### Layout grid

The grid is **96 columns wide** (verified via inspection of returned panel layouts on April 2026 OpenObserve Cloud). Older docs mention 192 or 48 — when in doubt, GET an existing dashboard from the same org and copy the `w` values you see. Heights are unitless rows (`h: 7` = small metric panel; `h: 14` = standard table).

### Useful `config` keys

| Key                  | Effect                                                                                                           |
| -------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `decimals`           | Number of decimal places for all numeric columns (0 = integers).                                                 |
| `unit`               | `numbers \| currency \| bytes \| seconds \| milliseconds \| microseconds \| nanoseconds \| percent \| percent-1` |
| `unit_custom`        | When `unit=currency`, ISO code like `USD`.                                                                       |
| `show_legends`       | Boolean, charts only.                                                                                            |
| `legends_position`   | `right \| bottom`.                                                                                               |
| `axis_border_show`   | Boolean.                                                                                                         |
| `line_interpolation` | `smooth \| linear \| step-start \| step-end`.                                                                    |
| `connect_nulls`      | Boolean — line/area only.                                                                                        |
| `top_results`        | Cap series count for line/bar (e.g. `10`).                                                                       |
| `mark_line`          | `[{name, type:'avg'\|'max'\|'min', value}]` — horizontal reference lines.                                        |

## 6. Critical pitfalls

**6a. Re-aggregation when `customQuery: true`** — the most common bug.

If your hand-written SQL already contains `COUNT(*)`, `SUM(...)`, `AVG(...)` etc., every entry in `fields.y` (and `fields.x`) **must set `aggregationFunction: null`**. Default `'sum'` causes OpenObserve to wrap the already-aggregated column in another aggregation client-side, producing **duplicate rows** and wildly inflated numbers.

```jsonc
// WRONG — produces duplicate rows
"y": [{"column":"messages", "aggregationFunction":"count"}]

// RIGHT — SQL already did the aggregation
"y": [{"column":"messages", "aggregationFunction":null, "treatAsNonTimeseries":true}]
```

**6b. Multiple `fields.y` on Table panels** — each Y entry can render as a separate series/row. For a Table that should display one row per group, put **only one entry** in `fields.y` (any one column); the renderer will then display all SQL columns as table columns.

**6c. Metric panels with `customQuery: true`** — must explicitly map the result column to `fields.y`:

```json
"y": [{"label":"Value", "alias":"value", "column":"value", "aggregationFunction":"sum", "treatAsNonTimeseries":false}]
```

The metric panel needs to know which column is the number to display.

**6d. ROUND + wildcard timestamp expansion** — OpenObserve's planner sometimes auto-injects `_timestamp` into queries that wrap `SUM(col)` in `ROUND(...)`, producing `Column "_timestamp" must appear in the GROUP BY clause` errors. Workaround: drop `ROUND()` and use the panel's `decimals` config instead, or pre-cast: `CAST(SUM(...) AS DOUBLE)`.

**6e. Hash-based concurrency on PUT** — every successful PUT changes the dashboard hash. If you mutate a dashboard from two scripts back-to-back, the second one needs to refetch. Always re-`GET` before each `PUT` to grab the current hash.

**6f. `start_time`/`end_time` are microseconds** — `Date.now() * 1000`, not milliseconds. Off-by-1000× returns no hits but no error.

## 7. Folders / alerts / ingestion

**Folders** (v2 API):

```bash
curl $AUTH "$BASE/folders/dashboards" # list
curl $AUTH -X POST "$BASE/folders/dashboards" -d '{"name":"my-folder"}'
curl $AUTH "$BASE/folders/dashboards/name/<folder_name>" # lookup by name
```

`folder_type` ∈ `dashboards | alerts | reports`.

**Alerts**:

```bash
curl $AUTH "$BASE/{stream}/alerts" # list per-stream
curl $AUTH -X POST "$BASE/{stream}/alerts" -d '{...}'
# templates and destinations are referenced by alert definitions:
curl $AUTH "$BASE/alerts/templates"
curl $AUTH "$BASE/alerts/destinations"
```

**Ingestion** (POST your own data in):

```bash
# JSON
curl $AUTH -X POST "$BASE/<stream>/_json" -d '[{"event":"foo","level":"info"}]'

# Multi-line JSON (one per line)
curl $AUTH -X POST "$BASE/<stream>/_multi" --data-binary @file.ndjson

# Elasticsearch bulk
curl $AUTH -X POST "$BASE/_bulk" --data-binary @bulk.txt

# OTLP HTTP
curl $AUTH -X POST "$BASE/v1/logs" -d @otlp-logs.json
curl $AUTH -X POST "$BASE/v1/traces" -d @otlp-traces.json
curl $AUTH -X POST "$BASE/v1/metrics" -d @otlp-metrics.json

# Loki
curl $AUTH -X POST "$BASE/loki/api/v1/push" -d @loki.json

# Prometheus remote-write (binary protobuf)
curl $AUTH -X POST "$BASE/prometheus/api/v1/write" --data-binary @write.pb
```

## 8. Common recipes

**Get top hosts by message count (last 24h)**:

```bash
NOW=$(($(date +%s) * 1000000))
DAY=$((NOW - 86400 * 1000000))
curl $AUTH -H 'Content-Type: application/json' \
  "$BASE/_search?type=logs" \
  -d "{\"query\":{\"sql\":\"SELECT host_name, COUNT(*) AS n FROM \\\"my_stream\\\" GROUP BY host_name ORDER BY n DESC\",\"start_time\":$DAY,\"end_time\":$NOW,\"size\":50}}"
```

**Add a metric panel to an existing dashboard** (single-shot, hash-aware):

```bash
DASH_ID=<dashboard_id>
HASH=$(curl -s $AUTH "$BASE/dashboards/$DASH_ID?folder=default" | jq -r .hash)
curl $AUTH -X POST -H 'Content-Type: application/json' \
  "$BASE/dashboards/$DASH_ID/panels?folder=default&hash=$HASH" \
  -d '{
    "tabId": "default",
    "panel": {
      "id": "p-cost",
      "type": "metric",
      "title": "Total cost (USD)",
      "queryType": "sql",
      "queries": [{
        "query": "SELECT SUM(CAST(cost_usd AS DOUBLE)) AS value FROM \"my_stream\"",
        "customQuery": true,
        "fields": {
          "stream":"my_stream", "stream_type":"logs",
          "x":[], "z":[], "breakdown":[],
          "y":[{"label":"Value","alias":"value","column":"value","aggregationFunction":"sum","treatAsNonTimeseries":false}],
          "filter":{"filterType":"group","logicalOperator":"AND","conditions":[]}
        },
        "config":{}
      }],
      "config": {"unit":"currency","unit_custom":"USD","decimals":2},
      "layout": {"x":0,"y":0,"w":32,"h":7,"i":99}
    }
  }'
```

**Build a complete dashboard from scratch**: GET an existing dashboard's panel JSON as a template (it's the safest way to learn the exact field shapes the server will accept), then mutate the `tabs[0].panels` array and PUT the unwrapped v8 body back. See the `references/recipes/build-dashboard.sh` script that ships with this skill for a working example.

## 9. SDKs / clients (no first-party CLI)

| Language              | Repo                                                | Status                   |
| --------------------- | --------------------------------------------------- | ------------------------ |
| Python                | `github.com/openobserve/openobserve-python-sdk`     | Active                   |
| Go                    | `github.com/openobserve/openobserve-go-client`      | ZincObserve-era, partial |
| Helm chart            | `github.com/openobserve/openobserve-helm-chart`     | Active                   |
| OTel collector distro | `github.com/openobserve/openobserve-otel-collector` | Active                   |

For most agent tasks, plain `curl` against the REST API is the right tool — the SDKs add little value over an HTTP request and lag the server feature set.

## References

- API docs (canonical): https://github.com/openobserve/openobserve-docs (path: `docs/reference/api/`)
- Server source: https://github.com/openobserve/openobserve (paths: `src/handler/http/request/`, `src/config/src/meta/dashboards/v8/mod.rs`)
- Cloud console: https://cloud.openobserve.ai (regions: us1, eu1, ap1)
- The `references/` directory in this skill mirrors selected docs from `openobserve-docs` for offline access.

© fcakyon · Apache-2.0 · fcakyon/claude-codex-settings

Similar skills

All skills for DevOps and infrastructure →

From the same set113

The whole set →
ui-regression ui-regression verifies web apps and browser extensions on localhost, staging, or production across user flows, recovery states, locales, and viewports. CX Codex +1 ★ 1,216repo stars humanize humanize is a Claude Code skill for revising text to sound natural while keeping its meaning. It activates on requests to edit replies, docs, comments, emails, and other writing. CX Codex +1 ★ 1,216repo stars writing-guidelines writing-guidelines audits technical documentation, guides, and interface copy against strict editorial rules and AI phrasing patterns. CX Codex +1 ★ 1,216repo stars aeo This skill builds AEO plans, reviews AI answers and sources, and maps content work for products that need to appear in buyer-focused AI search. CX Codex +1 ★ 1,216repo stars polar-billing polar-billing is a Claude Code skill that documents Polar billing architecture, including models, Stripe payments, subscriptions, and benefit provisioning. CX Codex +1 ★ 1,216repo stars agent-browser This skill guides an agent through website tasks with agent-browser, from locating page controls to filling forms and capturing screenshots. Use it to gather web data or test a web app. CX Codex +1 ★ 1,216repo stars reusable-app-components reusable-app-components is a Claude Code plugin for storing and reusing verified app flows with code, designs, and integration checks. It avoids duplicate testing of standard workflows. CX Codex ★ 1,216repo stars qa The qa plugin for Claude Code and Codex tests real application journeys with saved sessions. It records failure evidence when test steps break. CX Codex ★ 1,216repo stars

Project sponsors

Companies that keep this analytics open