Monitoring and reports

What do monitoring and reports do in Serpel?

A monitoring run is one background job. It checks the Google position of every tracked keyword (see rank tracking), sends every AI prompt to ChatGPT and, if you switched it on, to Google AI Overview (see AI visibility), and then writes a report. No run, no report.

A run doesn’t crawl your website. The audit part of a report comes from the latest completed crawl. If only one of the two checks fails, Serpel still writes the report with the other. If both fail, the run fails and no report exists. Every run shows up under History (see history and exports).

How do you start a monitoring run by hand?

1. 1

   Open the project overview.

   The monitoring strip shows the frequency, the last run, the next run and the email status. The Reports page has the same button when no report exists yet.

2. 2

   Press Check now.

   The button shows the credit estimate, and viewers don’t see it. On the overview it stays disabled until the project has a keyword or prompt. On the Reports page it is always active, and without a keyword or prompt the request fails with “Monitoring needs a project with at least one keyword or AI prompt.”

3. 3

   Open the report.

   Serpel answers “Monitoring run queued”. If a run is already in progress you get “Monitoring is already running” and pay nothing extra. When the job ends, Latest report opens the result.

A manual run doesn’t move the schedule. Its report is compared with the previous report.

How do monitoring schedules work?

Schedules live in Project settings → Monitoring. Frequency decides how often a run starts and Time decides at which hour. New projects start with Manual only at 05:00.

Time offers every full hour from 00:00 to 23:00 and always means Europe/Berlin time, although the field doesn’t say so. Only the Recipients dialog names it, in the hint under Not before (“Time zone Europe/Berlin.”) once a frequency is set. Serpel looks for due schedules about once a minute, so a run starts at the chosen hour or shortly after. If that hour has already passed when you first switch a schedule on, the first run can start right away. Saving Daily on a plan without it is rejected, and the dropdown shows “Pro plan only”.

If a queued result hasn’t arrived after 45 minutes, Serpel checks that keyword immediately and still charges the scheduled price.

What is the weekly crawl?

Weekly crawl is a switch in the same section. When it is on, Serpel starts a site crawl every Monday at the hour you chose and compares it with the previous crawl (see site audit). The crawl is a separate job with its own credits, and its score shows up in the next report.

What does monitoring cost?

A run costs credits for the checks it delivers. The report, the emails and the webhook messages are free, and a keyword or prompt that fails costs nothing. See credits and billing for balances and top-ups.

A weekly crawl adds 1 credit per started 20 pages. Under the schedule fields, a forecast strip shows Monitored, Runs per month, Credits per month and Balance lasts, so you see the effect of a change before you save.

Example: 50 keywords and 10 prompts, with Google AI Overview on, cost 50 × 2 + 10 × (2 + 2) = 140 credits per run. A 100-page crawl costs 5. Weekly, that is about 4.3 runs and crawls a month, or roughly 622 credits.

What does a monitoring report contain?

Every report starts with a one-line headline, for example “Visibility 31.40 (+4.2%). 1 keyword improved, 1 declined.” The report page adds these parts:

• Keyword figures: visibility, average position, keywords in the top 3 and top 10, and estimated clicks per month. Visibility is the share of possible clicks you reach, weighted by search volume. 100% means every keyword ranks first.
• Movement: keywords that moved up, dropped, entered or left the checked depth, with the places gained or lost.
• All keywords and Competitors: position, change, URL and search volume per keyword, and visibility per domain (see competitors).
• AI visibility: how many ChatGPT answers cite or mention you, which prompts are newly cited or lost, and how often Google AI Overview cites you.
• Site audit: score against the previous crawl, issue counts and new or fixed issues. It says “No completed crawl yet” until a crawl has finished.

The first report has nothing to compare with and says “first report, no comparison”. From the second run on, every change is measured against the previous run.

How do you read reports and mark them as read?

The Reports page of a project lists its reports, newest first. The Reports area in the sidebar shows the 20 most recent reports of all your projects under Unread and Earlier, with a dot while something is unread. Opening a report marks it as read. On the Reports page, the command Mark all reports as read (Ctrl K) clears the list.

How does email delivery work?

Open Project settings → Monitoring, find Email report, press Recipients, type an address and press Add. A project can have up to 10 recipients, and they don’t need a Serpel account. After every run Serpel sends the report as an HTML email to every active recipient. Only owners and editors can change recipients.

• Test email to all sends the latest report, marked as a test, to every recipient. The send icon next to an address tests one recipient. Before the first report, the test is a short confirmation.
• Preview opens the latest email in a new tab. On a report page, Email preview does the same and Send by email sends that report again to all active recipients. The Email figure there shows Sent, Pending, Failed, Unsubscribed or Not sent.
• Every email has an Unsubscribe link and a one-click unsubscribe header. An address that unsubscribed shows an Unsubscribed badge and can’t be added again.

How do Slack, Discord and custom webhooks work?

A report can also go to a chat channel or your own endpoint. All three targets work together, and each report is posted to every target that is set up. Turn on the switch in Project settings → Monitoring, paste the address and save.

• For Slack and Discord you can add a Channel name such as #seo-reports, up to 80 characters. It is only a label. The address decides where the message lands.
• Send test message posts a short test to the saved address, so save the address first.
• The Report to custom URL row appears once a custom address exists. Set the first one with serpel projects update and --webhook, or with notificationWebhookUrl in the API. A Slack or Discord address entered there is stored at the matching target.

What does the custom webhook payload look like?

Serpel sends a POST with Content-Type: application/json and the event name report.created. The sample is abridged: in a real payload each list holds at most 10 entries, text also carries the ranking, AI and audit lines, and the summary also carries a keywordMonitoring object with the full keyword and competitor tables when the project tracks keywords.

{
  "event": "report.created",
  "project": {
    "id": "0b6f0f0e-6d1a-4c8e-9a53-4f9d2d7b8a10",
    "name": "Northwind Roasters",
    "domain": "northwind.example"
  },
  "report": {
    "id": "5c1e8a47-2d3b-4f60-9e1a-7b8c9d0e1f23",
    "url": "https://serpel.app/p/0b6f0f0e-6d1a-4c8e-9a53-4f9d2d7b8a10/reports/5c1e8a47-2d3b-4f60-9e1a-7b8c9d0e1f23",
    "summary": {
      "headline": "Visibility 31.40 (+4.2%). 1 keyword improved, 1 declined. Cited in 2 of 6 AI answers. Audit score 83 (+4).",
      "rankings": {
        "tracked": 17,
        "checked": 17,
        "top10": 9,
        "improved": [{ "keyword": "specialty coffee beans", "before": 5, "after": 2 }],
        "declined": [{ "keyword": "pour over coffee guide", "before": 6, "after": 7 }],
        "enteredTop10": [],
        "leftTop10": [],
        "aiOverviewCited": 1,
        "aiOverviewPresent": 4
      },
      "aiVisibility": {
        "prompts": 6,
        "cited": 2,
        "mentioned": 3,
        "newlyCited": ["Best specialty coffee subscription?"],
        "lostCitations": []
      },
      "audit": {
        "crawlId": "7d2a4c1e-3b9f-4e0a-8c55-2f61b0a9d3e4",
        "finishedAt": "2026-11-02T05:41:12.000Z",
        "score": 83,
        "scoreBefore": 79,
        "issueCounts": { "error": 1, "warning": 6, "notice": 12 },
        "newIssues": [],
        "resolvedIssues": [{ "code": "title_missing", "title": "Title is missing", "severity": "error" }]
      }
    }
  },
  "text": "Serpel: Report for Northwind Roasters (northwind.example)\nVisibility 31.40 (+4.2%). 1 keyword improved, 1 declined. …\nOpen report: https://serpel.app/p/0b6f0f0e-6d1a-4c8e-9a53-4f9d2d7b8a10/reports/5c1e8a47-2d3b-4f60-9e1a-7b8c9d0e1f23"
}

A test message for the custom webhook uses the event webhook.test and contains only event, project and text. Check the event field in your endpoint, for example report.created or webhook.test, because more event types can arrive at the same address. Your endpoint must answer with a 2xx status within 10 seconds. A redirect, an error status or a timeout counts as a failed delivery, which doesn’t fail the run: the report is saved and shows “Webhook delivery failed” with the reason.

What pauses a schedule and how do you resume it?

The weekly crawl follows the same rules. Nothing is deleted while a schedule is paused, and manual runs keep working while you have credits and the project fits the plan.

1. 1

   Check the overview.

   A paused schedule shows no error. Next run stays at “on the next worker run” and no new report appears.

2. 2

   Fix the cause.

   Add credits under Settings → Billing, or remove keywords or prompts, pick a lower Frequency or upgrade the plan.

3. 3

   Wait a few minutes.

   The scheduler starts the missed run on its next pass. Check now only creates an extra run and report.

How do you use monitoring from the CLI, API or MCP?

The CLI and the REST API cover everything on this page. Starting a run needs rankings:write, reading reports needs projects:read, and recipients, schedules and webhooks need projects:write. serpel monitoring run with --wait blocks until the report exists and prints its headline. serpel reports preview and serpel reports send cover the email preview and resend.

serpel projects update "$PROJECT_ID" --schedule weekly --schedule-hour 6 --crawl-schedule weekly
serpel monitoring run --project "$PROJECT_ID" --wait --timeout 900
serpel reports list --project "$PROJECT_ID" --unread
serpel reports show "$REPORT_ID"
serpel reports read "$REPORT_ID"
serpel monitoring recipients add --project "$PROJECT_ID" --email team@example.com
serpel monitoring email-test --project "$PROJECT_ID"
serpel projects update "$PROJECT_ID" --slack-webhook "$SLACK_WEBHOOK_URL" --slack-channel seo-reports
serpel monitoring webhook-test --project "$PROJECT_ID" --channel slack

curl -X POST https://serpel.app/api/v1/projects/$PROJECT_ID/monitoring/run \
  -H "Authorization: Bearer $SERPEL_TOKEN"

curl "https://serpel.app/api/v1/reports?projectId=$PROJECT_ID&unread=true&limit=10" \
  -H "Authorization: Bearer $SERPEL_TOKEN"

curl -X PATCH https://serpel.app/api/v1/projects/$PROJECT_ID \
  -H "Authorization: Bearer $SERPEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"rankSchedule": "weekly", "rankScheduleHour": 6, "crawlSchedule": "weekly"}'

A new run answers with HTTP 202 and the job, or with HTTP 200 and alreadyRunning: true if one is in progress. Reports have GET /reports, GET /reports/{id}, POST /reports/{id}/read and POST /reports/read-all. Recipients live at /projects/{id}/report-recipients, and POST /projects/{id}/webhook/test sends the test message. The MCP server has no report tool. An agent can follow a run with get_job_status and read positions with get_keyword_rankings, see the MCP setup for Claude Code.

Where to go next