How do I let an AI SRE look at JSON API endpoints when investigating error spikes?

Tares polls any JSON endpoint on a schedule with the http_poll connector and stores one event per item, so your AI SRE can see business data next to the telemetry. When an error spike hits, the agent can check who was affected, not only how many errors fired. For rows in your own database, the postgres connector reads new and changed rows incrementally on a cursor column.

How it works

The http_poll connector calls the endpoint itself on the source’s poll interval. No script runs on your side. This is the path for APIs Tares calls. Systems that call Tares use the webhook connector instead.

The reply becomes events like this:

• payload_key points at the part of the reply that is the payload, such as data or data.items. An object is one event. A list is one event per entry.
• event_time_field names the field holding the event’s time. Empty means the poll time.
• id_field is the deduplication key. An item seen in recent polls is not stored again. Empty stores every poll.
• event_type is the word trigger filters match and triggers count by. event_type_field reads it from a field of the item instead.
• text_template is a one-line summary of each event, with values from the payload in braces.

The payload is stored as received, so labels you declare later can still reach every field. Nested values are reachable by dotted name in labels, trigger filters and trigger conditions.

The postgres connector works on the same idea for tables. A cursor column that only grows, such as an autoincrement id or updated_at, tracks what it has read. A primary label, such as tenant_id, makes that column the entity key. Your application’s source-of-truth data lands in the same timeline as your telemetry. For the wider picture of how agents investigate, see AI SRE.

Set it up

1. Pick the endpoint that holds the business context for an incident, such as an endpoint that lists affected accounts, orders or users. Then choose how to create the source. You can ask a connected agent, describe the goal in the guided setup, or go to Sources → Add source → HTTP API (poll).
2. Fill in the method, the URL and, if the API wants one, a credential. A credential is one header name and value, stored as a secret. It is never returned by the API and never exported. credential_header names the header and defaults to Authorization. Put other headers the API needs in headers. For POST, add a body.
3. Press Discover. Tares calls the API once, shows the reply it got and fills in what becomes an event. Pick the entity key from the fields it saw, then create the source.
4. Adjust the mapping. This is the shape of an http_poll source, from the connector page. Adapt the URL, fields and labels to your API:

- name: weather_berlin
  connector: http_poll
  poll: 10m
  config:
    url: https://api.open-meteo.com/v1/forecast?latitude=52.52&longitude=13.41&current_weather=true
    event_type: weather
    event_time_field: current_weather.time
    id_field: current_weather.time
    text_template: 'Berlin wind {current_weather.windspeed} km/h, {current_weather.temperature} C'
    labels:
      - { name: city, const: berlin, primary: true }
      - { name: windspeed, field: current_weather.windspeed, type: number }

For a list API, use the entry’s id as id_field and set payload_key to the list. Declare one primary label for the entity you want to group by, such as the account. 5. If the affected-customer data lives in a database, add a postgres source instead. Enter the connection URL, press Discover, pick the table and choose the columns to pull:

- name: orders
  connector: postgres
  poll: 10s
  config:
    dsn: postgresql://user:pass@host:5432/appdb
    table: orders
    cursor_column: updated_at
    columns: id,tenant_id,status,amount,updated_at   # empty = every column
    labels:
      - { name: tenant_id, field: tenant_id, primary: true }
      - { name: status, field: status }

6. Verify. Open the source. Recent events shows each poll’s events with the summary line, and Fields lists every field seen with its coverage. Use it to confirm the key field is reliably present.

The connector keeps polling safe. It refuses a poll under 10 seconds. On a 429 or any 5xx it backs off, doubling the wait up to an hour, and it honors Retry-After. Any other 4xx shows as a config error on the source’s health.

What you get

• Business data in the same timeline as your telemetry, so an error spike can be read next to the accounts, orders or users around it.
• One event per item from any JSON endpoint, with the original payload kept so you can add labels later and reach every field.
• Incremental reads of table rows, so each poll brings in only new or changed rows.
• Number labels you can use in triggers. A trigger like max(windspeed) > 62 over 15m fires from the next reading that crosses the threshold. You can write the same kind of condition on a field from your own endpoint.
• Health on the source that tells you when the API is rate limiting or rejecting requests.

When something else fits

• If the system can call Tares, use the webhook connector. http_poll is for APIs that Tares has to call.
• If the data lives in a table you can reach, postgres reads rows on a cursor and is a better fit than wrapping the database in an API.

Related