How do I read only certain sources or one project’s data with the /read endpoint?

Tares lets you narrow a POST /read call by adding sources to name specific sources, or project to read only that project’s sources. By default /read takes a selector such as service set to checkout and a window such as 15m, and searches all sources. You get one time-ordered timeline back either way.

How it works

POST /read on the Tares daemon takes a JSON body. The body has three parts you care about:

• selector: a label and value pair, such as service equal to checkout. Tares returns events from every source that carries that label.
• window: how far back to look, such as 15m.
• sources or project (optional): a scope for the read.

With only a selector and a window, the read spans all sources. You need no setup for this. Events from logs, metrics and commits come back interleaved on one clock, ordered by time.

To narrow the read, add one of two keys:

• sources is a list of source names. Tares reads only those sources.
• project names a project. Tares reads only the sources that belong to that project.

The selector still applies in both cases. A scoped read returns the events that match the selector and also sit in the sources you named, or in the project you named. The MCP read tool maps onto this same endpoint, so an agent connected over MCP reads the same way. The HTTP API guide walks through the full loop, and the AI SRE guide shows where reads fit in an investigation.

Set it up

The steps below build two small sources, feed them events, and then read them three ways. You need a running daemon with the API at http://127.0.0.1:8787.

1. Start Tares.

tares up

2. Create two webhook sources. Both map the service field to a label marked primary, so one selector matches events in both.

curl -s -XPOST localhost:8787/api/sources -H 'content-type: application/json' -d '{
  "name": "checkout_probe",
  "connector": "webhook",
  "config": {
    "event_type": "probe",
    "text_template": "latency {latency_ms}ms on {endpoint}",
    "labels": [{ "name": "service", "field": "service", "primary": true }]
  }
}'
 
curl -s -XPOST localhost:8787/api/sources -H 'content-type: application/json' -d '{
  "name": "checkout_deploys",
  "connector": "webhook",
  "config": {
    "event_type": "deploy",
    "text_template": "deploy {version} of {service}",
    "labels": [{ "name": "service", "field": "service", "primary": true }]
  }
}'

3. Feed them. Locally you can post to a source by name. The first source gets two checkout events and one search event, and the second gets one checkout deploy.

curl -s -XPOST localhost:8787/ingest/checkout_probe -H 'content-type: application/json' \
  -d '{"service": "checkout", "endpoint": "/pay", "latency_ms": 120}'
curl -s -XPOST localhost:8787/ingest/checkout_probe -H 'content-type: application/json' \
  -d '{"service": "checkout", "endpoint": "/pay", "latency_ms": 1450}'
curl -s -XPOST localhost:8787/ingest/checkout_probe -H 'content-type: application/json' \
  -d '{"service": "search", "endpoint": "/q", "latency_ms": 45}'
curl -s -XPOST localhost:8787/ingest/checkout_deploys -H 'content-type: application/json' \
  -d '{"service": "checkout", "version": "v42"}'

4. Read across all sources. The selector filters by label, and the window sets the lookback.

curl -s -XPOST localhost:8787/read -H 'content-type: application/json' \
  -d '{"selector": {"service": "checkout"}, "window": "15m"}'

You get three events: the two checkout probes and the deploy, in time order. The search event is left out because its label value differs.

5. Narrow to specific sources by adding sources.

curl -s -XPOST localhost:8787/read -H 'content-type: application/json' \
  -d '{"selector": {"service": "checkout"}, "window": "15m", "sources": ["checkout_probe"]}'

Now you get only the two probe events. The deploy event drops out because checkout_deploys is not in the list.

6. Narrow to one project by adding project with the project’s id or name in place of sources. A source lands in the Default project unless you pass a project when you create it, so to keep a job separate, create a project first and pass its id or name as project on source creation. See Projects for how projects group sources.

What you get

• One correlated, time-ordered timeline for the entity you select, from every source by default.
• A scoped view when you need it: a short list of named sources, or everything in a single project.
• The same behavior from curl, from your own code and from an agent using the MCP read tool, because they share one endpoint.
• No setup for the default read. The selector and the window are enough.
• Clear separation between jobs. When sources live in different projects, a project read keeps one job’s data out of another’s results.

When something else fits

• Use the default read with no sources or project when you want logs, metrics and commits for one entity on a single clock. That is the main reason to read across sources.
• Use a trigger when you want Tares to wake an agent for you. The dispatch arrives with a correlated timeline already attached, so the agent does not need to call /read itself. The HTTP API guide shows the full flow.

Related