Measurement API

Paths on this page are relative to https://shruwd.io/api/v1.

Run a cycle

curl -X POST "https://shruwd.io/api/v1/brands/northwind/cycles" \
  -H "Authorization: Bearer $SHRUWD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Invoke-RestMethod -Method Post -Uri "https://shruwd.io/api/v1/brands/northwind/cycles" `
  -Headers @{ Authorization = "Bearer $env:SHRUWD_API_KEY" } `
  -ContentType "application/json" -Body '{}'

Creates a manual cycle due now and returns its id. It draws on the same period allowance as any cycle.

One manual cycle per brand at a time: while one is pending or running, another is 409 cycle_in_progress. On a free plan this is the one snapshot, and is 409 snapshot_taken once used. A workspace paused pending review is 409 workspace_on_hold.

GET /brands/{brandId}/cycles?limit= returns recent cycles with their state and counts.

Read visibility

curl "https://shruwd.io/api/v1/brands/northwind/visibility?engine=google_aio" \
  -H "Authorization: Bearer $SHRUWD_API_KEY"

Invoke-RestMethod -Uri "https://shruwd.io/api/v1/brands/northwind/visibility?engine=google_aio" `
  -Headers @{ Authorization = "Bearer $env:SHRUWD_API_KEY" }

Returns { engine, range, asOf, nResponses, entities, prompts, intents }. Each entity carries mentionRate and shareOfVoice, each with its interval or an explicit insufficient_data, and avgProminence: an average with no interval, near 1 when the entity is named at the start of the answer, null when it was never named.

firstNamed is how often the entity is the first of your tracked companies an answer names, with its interval, over the answers share of voice uses. It is computed when a cycle closes, for 7-, 30- and 90-day ranges; for any other range it is undefined. An untracked company can come earlier, so read it as a sign of being the first pick, not a recommendation.

intents is prompts pooled by question type, buying first: commercial, comparison, problem, informational, navigational, each only when a prompt has it. Each row carries prompts (how many it pools), the summed counts, and selfMentionRate with its own n. Like prompts it covers from to to, while entities describe asOf, so the totals can differ by a few days' runs.

If from reaches past your plan's history window it is clamped, and the response says so in historyFrom rather than failing.

Read the trend

curl "https://shruwd.io/api/v1/brands/northwind/visibility/series?window=30" \
  -H "Authorization: Bearer $SHRUWD_API_KEY"

Invoke-RestMethod -Uri "https://shruwd.io/api/v1/brands/northwind/visibility/series?window=30" `
  -Headers @{ Authorization = "Bearer $env:SHRUWD_API_KEY" }

Returns points (one per cycle close) and, per entity, a series index-aligned with it. A point below the display floor is insufficient_data, never a number.

modelChanges lists the moments the provider changed its underlying models. A difference spanning one of those may be the model rather than you — see When a number has moved.

Read crawler activity

curl "https://shruwd.io/api/v1/brands/northwind/crawlers" \
  -H "Authorization: Bearer $SHRUWD_API_KEY"

Invoke-RestMethod -Uri "https://shruwd.io/api/v1/brands/northwind/crawlers" `
  -Headers @{ Authorization = "Bearer $env:SHRUWD_API_KEY" }

Per-bot activity with verified and unverified hits kept separate. Only verified hits count toward anything.

daily carries a per-day series per bot, index-aligned with daily.days.

Read crawler activity per path

Where a bot's errors came from:

curl "https://shruwd.io/api/v1/brands/northwind/crawlers/paths?bot=oai_searchbot&status=error" \
  -H "Authorization: Bearer $SHRUWD_API_KEY"

Invoke-RestMethod -Uri "https://shruwd.io/api/v1/brands/northwind/crawlers/paths?bot=oai_searchbot&status=error" `
  -Headers @{ Authorization = "Bearer $env:SHRUWD_API_KEY" }

One row per bot and path, verified hits only. worstStatus tells a missing page (404) from a refusal (403). totalPaths above the rows returned means the list was cut.

Read the sources the answers cite

Which sites and pages the answers cite, and whose they are:

curl "https://shruwd.io/api/v1/brands/northwind/sources?engine=google_aio" \
  -H "Authorization: Bearer $SHRUWD_API_KEY"

Invoke-RestMethod -Uri "https://shruwd.io/api/v1/brands/northwind/sources?engine=google_aio" `
  -Headers @{ Authorization = "Bearer $env:SHRUWD_API_KEY" }

One row per site, most-cited first. answers counts the answers citing it, and rate is the share of all answers in answers.total, with its interval, or an explicit insufficient_data below ten answers. byEngine gives each engine's count with its own total. totalSources above the rows returned means the list was cut.

kind says whose a site is: yours or competitor when it is a company you track (named in owner), otherwise review_directory, forum, wikipedia, video or editorial (any other site: a blog, a publication, a vendor). yourAnswers counts the answers citing your own pages there, or videos on one of your YouTube channels. Each site carries its five most-cited pages, without tracking parameters; for a video, the page's owner is the company whose channel published it. findings lists up to three findings about the site that are still open or being fixed.

answers.citingAny is how many answers cite any source at all. ChatGPT often answers without citing anything, so read a share against it: a site in 30% of answers matters more where every answer cites something. It is null when part of the range predates 2026-11-02, when Shruwd started counting it.

Read individual answers

curl "https://shruwd.io/api/v1/brands/northwind/answers?limit=10" \
  -H "Authorization: Bearer $SHRUWD_API_KEY"

Invoke-RestMethod -Uri "https://shruwd.io/api/v1/brands/northwind/answers?limit=10" `
  -Headers @{ Authorization = "Bearer $env:SHRUWD_API_KEY" }

limit is 1–50, default 10. Newest first, measured runs only.

promptGroupId narrows the list to one prompt, and engine to one engine. A finding on a prompt carries that prompt's id as its subjectRef, so this reads the answers behind it:

curl "https://shruwd.io/api/v1/brands/northwind/answers?promptGroupId=$groupId&limit=50" \
  -H "Authorization: Bearer $SHRUWD_API_KEY"

Invoke-RestMethod -Uri "https://shruwd.io/api/v1/brands/northwind/answers?promptGroupId=$groupId&limit=50" `
  -Headers @{ Authorization = "Bearer $env:SHRUWD_API_KEY" }

Each answer carries prompt, engine, state, executedAt, whether you were mentioned and at what rank, the surrounding context, the competitors named, and the citations with isSelf marked: a page on your domains, or a video on one of your YouTube channels. ownedVia says which, site or channel.

Next steps

• Findings — the diagnosed causes behind these numbers
• Metric definitions — what each number counts