canonical: https://jentic.com/apis/pcp.io/pcp

# PCP PMWEBAPI

Performance Co-Pilot (PCP) PMWEBAPI provides REST API access to system performance metrics, time series data, full-text search, and live host monitoring via the pmproxy daemon. It exposes the PMAPI for querying real-time metric values, the Series API for historical time series queries, and the Search API for discovering metrics by name, description, or instance domain. The API runs on port 44322 and serves performance data from any PCP-instrumented host.

## For AI agents

Query real-time performance metrics, search for metric names, retrieve time series data, and browse metric hierarchies from PCP-instrumented hosts.

## Scope

Does not handle metric alerting, dashboard rendering, or log aggregation - use for raw metric collection, time series queries, and metric discovery only.

## Capabilities

- Fetch real-time values for any PCP performance metric from instrumented hosts
- Query historical time series data with filtering by label and time range
- Search for metrics by name, description, or instance domain via full-text index
- Browse the metric namespace hierarchy with children and descriptor lookups
- Retrieve instance domain members for multi-instance metrics
- Export all metric values in Prometheus-compatible exposition format

## Use cases

### Real-Time Infrastructure Monitoring

Fetch live performance metrics from PCP-instrumented Linux hosts. The PMAPI endpoints return current values for any metric in the PCP namespace (CPU, memory, disk, network, process-level counters). Agents create a polling context via GET `/pmapi/context`, then fetch specific metrics via GET `/pmapi/fetch` with metric names. This enables real-time dashboards and alerting without installing additional agents.

Example prompt: Create a PMAPI context via GET `/pmapi/context` with hostspec=localhost, then fetch the current value of kernel.all.cpu.idle via GET `/pmapi/fetch`

### Time Series Analysis

Query historical performance data stored in PCP archives for capacity planning and trend analysis. The Series API provides time-windowed queries with label-based filtering across all archived metrics. Agents use GET `/series/query` with a PCP query expression to retrieve timestamped values, enabling performance regression detection and resource forecasting.

Example prompt: Query the time series for disk.dev.read over the last 3600 seconds via GET `/series/query` with the appropriate series expression

### Metric Discovery and Search

Find relevant performance metrics across a PCP deployment using full-text search. The Search API indexes metric names, help text, and instance domain descriptions. Agents query GET `/search/text` with keywords to discover available metrics without knowing exact namespace paths, enabling self-service monitoring setup.

Example prompt: Search for all network-related metrics via GET `/search/text` with query='network throughput' and return the matching metric names and descriptions

### AI Agent Infrastructure Monitoring via Jentic

AI agents use the PCP PMWEBAPI through Jentic to monitor infrastructure health, query performance metrics, and detect anomalies on PCP-instrumented hosts. Jentic handles Basic authentication and host targeting so agents can query multiple PCP instances from a single intent search without managing connection state.

Example prompt: Search Jentic for 'fetch CPU metrics from PCP', load the schema for GET `/pmapi/fetch`, and execute with metric names=['kernel.all.cpu.user', 'kernel.all.cpu.idle']

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/pmapi/context` | Create a PMAPI context for a host or archive |
| GET | `/pmapi/fetch` | Fetch current metric values |
| GET | `/pmapi/metric` | Look up metric descriptors |
| GET | `/pmapi/children` | Browse metric namespace hierarchy |
| GET | `/series/query` | Query historical time series data |
| GET | `/search/text` | Full-text search for metrics |
| GET | `/metrics` | Export metrics in Prometheus format |
| GET | `/series/values` | Retrieve time series values by series ID |

## Key resources

- **PMAPI Context** — Create and manage metric query contexts for host connections
- **PMAPI Fetch** — Retrieve current metric values from live hosts
- **PMAPI Metric** — Look up metric descriptors and metadata
- **Series** — Query, describe, and list historical time series data
- **Search** — Full-text search across metric names, descriptions, and instances
- **Metrics Export** — Export all values in Prometheus exposition format

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 38 / 100
- **Maturity:** Non-Ready
- **Dimensions:**
  - Foundational Compliance: 59 / 100
  - Developer Experience & Jentic Compatibility: 62 / 100
  - AI-Readiness & Agent Experience: 46 / 100
  - Agent Usability: 94 / 100
  - Security: 10 / 100
  - AI Discoverability: 79 / 100
- **View full report:** https://jentic.com/apis/pcp.io/pcp/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the PCP PMWEBAPI by hand means managing HTTP basic auth against your own pmproxy host on port 44322, establishing a metric context, and constructing time series queries yourself. Through Jentic you install once, import PCP PMWEBAPI from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** PCP PMWEBAPI passes its metric names and query terms as request parameters rather than in the URL path, so scope the agent by the operations it needs, such as fetching metrics, querying a time series, or discovering metrics by text search. You choose that set, so only the read operations you list are available to the agent.
- **Credential handling:** Your PCP basic auth credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'fetch CPU metrics from a server' or 'query a metric time series', and Jentic returns the matching PCP PMWEBAPI operation with its input schema targeting the configured pmproxy so the agent calls the right endpoint without reading the reference docs.

## Related APIs

- **OpenObserve API** — Observability platform that can ingest and visualize PCP metric data
- **Proxmox VE API** — Virtual environment manager whose hosts can be monitored via PCP agents
- **Proxmox Backup Server API** — Backup infrastructure that benefits from PCP performance monitoring

## FAQ

### What authentication does the PCP PMWEBAPI use?

The PCP PMWEBAPI uses HTTP Basic Authentication when configured in pmproxy. By default, pmproxy runs without authentication on port 44322. When auth is enabled, you provide username and password via the standard Authorization header. Through Jentic, credentials are injected automatically into each request.

### Can I query historical metric data with the PCP PMWEBAPI?

Yes. The Series API endpoints (GET `/series/query`, GET `/series/values`) provide access to historical data stored in PCP archives. You submit a query expression specifying the metric name and time window, and the API returns timestamped values from the archive.

### What are the rate limits for the PCP PMWEBAPI?

PCP PMWEBAPI is self-hosted via the pmproxy daemon, so there are no vendor-imposed rate limits. Performance depends on the host resources and the number of metrics being served. Each GET `/pmapi/fetch` call reads directly from the PMDA (Performance Metrics Domain Agent) for the requested metric.

### How do I search for metrics through Jentic?

Search Jentic for 'find PCP performance metrics', load the schema for GET `/search/text`, and execute with a query parameter like 'disk throughput'. Jentic handles authentication and returns matching metric names with descriptions and instance domains.

### Can I export PCP metrics to Prometheus?

Yes. The GET /metrics endpoint exports all available PCP metric values in Prometheus exposition format. This enables Prometheus scrapers to collect data from PCP-instrumented hosts without installing additional exporters.

### Can I limit what my agent is allowed to do with the PCP PMWEBAPI?

Yes. Because your Jentic One instance is self-hosted, you decide which PCP PMWEBAPI operations the agent may call, and only the read operations you list are available to it. For example, you can allow it to fetch current metric values with GET `/pmapi/fetch` while withholding time series queries via GET `/series/query` or full-text discovery via GET `/search/text.` The agent cannot reach any operation you leave out, and your basic auth credentials are supplied at execution time rather than exposed to the agent.