---
title: "corecluster_logs_query"
url: https://docs.corefinity.com/mcp/tools/corecluster_logs_query
type: tool
last_updated: 2026-11-13
feature: logs
related:
  - https://docs.corefinity.com/api/reference/logs/query-cluster-logs.md
  - https://docs.corefinity.com/guides/sites/logs-and-monitoring/logs.md
---
# corecluster_logs_query

**Query CoreCluster logs.** LogsQL search across a CoreCluster's sites: lines newest first, each naming its site, with a cursor; or a table per log account. Scope: read.

- Scope: `read`
- Runs as a task: no

## When to use it

Search the logs of a CoreCluster's sites at once with LogsQL over a time window: the matching lines newest first, each naming its site, with a cursor for the next page; or one table per log account for a query ending in stats, uniq or top. Use it when a problem may come from another site on the same cluster; for one site, `corestack_logs_query`.

## Inputs

- `cluster_id` (integer, ≥ 1, required): The CoreCluster.
- `sites` (array of integer, up to 200 items): The site ids (production rows) of this cluster to read, each once; omitted or empty: every site you may see on it. `corestack_site_list` with `cluster_id` names them.
- `environment` (one of `production`, `all`, default `"production"`): production (the default): each site's production row; all: its environments too.
- `source` (one of `all`, `web-access`, `web-error`, `php`, `app`, `cron`, `database`, `cache`, `search`, `queue`, default `"all"`): One log source.
- `query` (string, up to 4096 characters): LogsQL, sent as written (* when empty).
- `filters` (object): The filter builder's entries (level, text, fields), ANDed with the query.
- `from` (string): ISO 8601; with to, instead of range.
- `to` (string): ISO 8601; defaults to now.
- `range` (one of `15m`, `1h`, `6h`, `24h`, `7d`, `30d`): Back from now, inside the cluster's retention.
- `limit` (integer, 1–1000, default `200`)
- `cursor` (string, up to 65536 characters): next_cursor from the previous page.
- `facets` (array of string, up to 20 items): Fields whose top ten values to add (a records page only); a name that is not a field name is left out.

### Input schema

```json
{
  "additionalProperties": false,
  "properties": {
    "cluster_id": {
      "minimum": 1,
      "type": "integer"
    },
    "cursor": {
      "description": "The previous page's next_cursor.",
      "maxLength": 65536,
      "type": "string"
    },
    "environment": {
      "default": "production",
      "enum": [
        "production",
        "all"
      ],
      "type": "string"
    },
    "facets": {
      "items": {
        "type": "string"
      },
      "maxItems": 20,
      "type": "array"
    },
    "filters": {
      "type": "object"
    },
    "from": {
      "format": "date-time",
      "type": "string"
    },
    "limit": {
      "default": 200,
      "maximum": 1000,
      "minimum": 1,
      "type": "integer"
    },
    "query": {
      "maxLength": 4096,
      "type": "string"
    },
    "range": {
      "enum": [
        "15m",
        "1h",
        "6h",
        "24h",
        "7d",
        "30d"
      ],
      "type": "string"
    },
    "sites": {
      "description": "Site ids; omitted: all.",
      "items": {
        "type": "integer"
      },
      "maxItems": 200,
      "type": "array"
    },
    "source": {
      "default": "all",
      "enum": [
        "all",
        "web-access",
        "web-error",
        "php",
        "app",
        "cron",
        "database",
        "cache",
        "search",
        "queue"
      ],
      "type": "string"
    },
    "to": {
      "format": "date-time",
      "type": "string"
    }
  },
  "required": [
    "cluster_id"
  ],
  "type": "object"
}
```

## Refusals

- `logs_not_collected`: none of the sites read has its logs collected on this cluster yet (or none is left after `sites`, `environment` and the token's pins); nothing to read.
- `logs_unavailable`: this source's logs start once the sites' next platform update has applied.
- `query_too_wide`: the read covers too many sites or too much text at once; name fewer `sites`, add a source or narrow the window.
- `logs_cluster_unavailable`: logs cannot be read at the moment; try again shortly.
- `tenant_mismatch` also answers a platform cluster, and a `sites` entry that is not one of this cluster's sites you may see.
- `invalid_arguments` with `fields.cursor`: the cursor is not this call's — another token's or person's, another query's, or past its window. Run the query again.
- The refusals every tool can answer: `invalid_arguments`, `tenant_mismatch`, `scope_required`, `pin_refused`, `rate_limited`, `temporarily_unavailable`, `internal_error` (corestack://guides/how-this-server-works).

While the logs servers are busy a read answers `logs_busy`; try again in a few seconds.

## Example

```json
{
  "name": "corecluster_logs_query",
  "arguments": {
    "cluster_id": 812,
    "sites": [4211, 4230],
    "source": "web-error",
    "range": "1h"
  }
}
```

## The answer

- `kind` is `records` (the lines newest first, `next_cursor` for the next page — send it back with the same arguments
  and `window`) or `table` (one table per log account for a query ending in an aggregating pipe; no cursor).
- Every line carries `site` `{id, label, environment}`. A query with any pipe is shown without site names (`site` is
  null throughout, and `warnings` says so): a pipe can drop or rewrite the field a line's site is read from.
- `tenant` is the cluster's logs tenant (quota and retention), or null when the read spans several. `window` `{from, to}`
  holds the absolute instants read; send them as `from` / `to` to read the same window again.
- A page cursor works only for this token and person, with the same query and window.
- **A large page comes as a link**, as `corestack_logs_query`'s: its metadata with `linked {uri, …}` and a
  `resource_link` to `corestack://logs/pages/{ref}`; read it with `resources/read` before it expires, under the same token.

## A token limited to some sites

The read holds only the rows the token's pins cover — its lines, and an export's file. A `sites` entry outside the pins
is `pin_refused` naming that site. Under a token limited to some environments of a site, leave `sites` out and send
`environment: "all"`: the read then covers exactly the rows the token may read.

## Prompt

```text
Using the Corefinity MCP server, call corecluster_logs_query with cluster_id 812, sites [4211,4230], source web-error, range 1h. (Query CoreCluster logs.) Tell me what it returned.
```

## The same task elsewhere

- Endpoint: [POST /api/corestack/clusters/{cluster}/logs/query](https://docs.corefinity.com/api/reference/logs/query-cluster-logs.md)
- Guide: [Logs](https://docs.corefinity.com/guides/sites/logs-and-monitoring/logs.md)
