Skip to content
Reports and Alerts

Reports and Alerts

Availability: Scheduled reports are available on every plan. Free includes one report that runs at most once a week. Alerts need Starter or higher, and higher plans allow more rules (see plans). API keys need reports:read to list and read rules, and reports:write to create, change and delete them.

A rule is a scheduled report or an alert, together with where it’s sent. It’s the same thing you build under Reports in the dashboard; see reports and alerts for what each section and condition does. Identify a rule by its public_id.

The API never returns destination secrets. Webhook URLs and tokens come back shortened to their scheme and host, for example https://hooks.slack.com/….

Endpoints

MethodPathScope
GET/api/v1/reports/rulesreports:read
GET/api/v1/reports/rules/{rule_public_id}reports:read
POST/api/v1/reports/rulesreports:write
PATCH/api/v1/reports/rules/{rule_public_id}reports:write
DELETE/api/v1/reports/rules/{rule_public_id}reports:write

You see the rules your role and teams give you access to, as in the dashboard. Owners, administrators and collaborators can create and change rules; read-only members can only read them.

List rules

Query parameterNotes
workspace_public_idOnly rules in this workspace. A key restricted to a workspace always lists that workspace.
schedule_typesComma-separated: every_x for scheduled reports, event for alerts.
link_public_idsComma-separated link public IDs. Only rules that cover these links.
team_public_idsComma-separated team public IDs. Only rules assigned to any of these teams.
curl "https://app.shortn.link/api/v1/reports/rules?workspace_public_id=8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10&schedule_types=every_x" \
  -H "Authorization: Bearer $SHORTN_API_KEY"
{
  "data": [
    {
      "public_id": "e7b2c4a9-1f6d-4b38-9c0a-5d2e8f1b7a63",
      "name": "Weekly traffic",
      "workspace_public_id": "8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10",
      "workspace_name": "Acme Marketing",
      "team_public_id": "",
      "team_name": "",
      "team_public_ids": [],
      "team_names": [],
      "workspace_wide": true,
      "schedule_type": "every_x",
      "schedule_interval_seconds": 604800,
      "next_run_at": "2026-11-23T08:00:00Z",
      "enabled": true,
      "trigger_count": 12,
      "report_name": "Weekly traffic",
      "report_query_type": "custom_builder_v1",
      "created_at": "2026-08-17T08:00:00Z",
      "destinations": [
        { "type": "email", "data": { "to": ["marketing@example.com"] } },
        { "type": "slack", "data": { "webhook_url": "https://hooks.slack.com/…" } }
      ]
    }
  ]
}
FieldNotes
schedule_typeevery_x for a scheduled report, event for an alert.
schedule_interval_seconds, next_run_atA report’s interval and next run. null for alerts.
enabledfalse while the rule is paused.
trigger_countHow many times the rule has run or fired.
team_public_ids, workspace_wideThe teams whose links the rule covers. Empty and true when it covers the whole workspace.

Get a rule

curl https://app.shortn.link/api/v1/reports/rules/e7b2c4a9-1f6d-4b38-9c0a-5d2e8f1b7a63 \
  -H "Authorization: Bearer $SHORTN_API_KEY"
{
  "data": {
    "public_id": "e7b2c4a9-1f6d-4b38-9c0a-5d2e8f1b7a63",
    "workspace_public_id": "8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10",
    "workspace_name": "Acme Marketing",
    "team_public_id": "",
    "team_public_ids": [],
    "team_names": [],
    "workspace_wide": true,
    "include_unassigned_links": true,
    "trigger_count": 12,
    "schedule_type": "every_x",
    "schedule_interval_seconds": 604800,
    "next_run_at": "2026-11-23T08:00:00Z",
    "enabled": true,
    "report_name": "Weekly traffic",
    "report_query_type": "custom_builder_v1",
    "destinations": [
      { "type": "email", "data": { "to": ["marketing@example.com"] } }
    ],
    "definition": {
      "version": "custom_builder.v1",
      "trigger": "scheduled",
      "sections": [
        { "id": "total_clicks", "order": 1, "settings": { "window": "7d" } },
        { "id": "top_links", "order": 2, "settings": { "top_n": 10 } }
      ],
      "filters": { "tag_public_ids": [] },
      "options": { "include_comparison": true, "attach_csv": false, "locale": "en-US" }
    }
  }
}

A single rule also returns:

  • definition: the sections or conditions the rule is built from;
  • include_unassigned_links: whether it also covers links in no team;
  • for alerts, watch_condition, watch_recurring and watch_reset_increment.

To get a valid definition to send when you create rules, build the report or alert once in the dashboard and read it here.

Create a rule

FieldTypeRequiredNotes
workspace_public_idstringYes, unless the key is restricted to a workspaceThe workspace the rule belongs to.
report_typestringYescustom_builder_v1: a report or alert built from the report library.
schedule_typestringNoevery_x (the default) for a scheduled report, event for an alert.
interval_secondsintegerFor reportsHow often the report runs, for example 86400 (daily) or 604800 (weekly). On Free, at least 604800.
initial_run_atstringNoA report’s first run, in RFC 3339. Defaults to one interval from now.
report_namestringNoThe rule’s name.
definition_jsonobjectYesThe sections or conditions. See the definition.
destination_public_idsarray of stringsYes, to deliver anywhereDestinations in the workspace.
team_public_idsarray of stringsNoTeams whose links the rule covers. Leave it out or send [] for the whole workspace.
include_unassigned_linksbooleanNoWith teams, also cover links in no team.
link_public_idsarray of stringsNoOnly cover these links.

The teams you can pick, and who can see the rule afterwards, follow the same rules as in the dashboard (see which links a report or alert covers).

curl -X POST https://app.shortn.link/api/v1/reports/rules \
  -H "Authorization: Bearer $SHORTN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_public_id": "8c0f6b52-4d0e-4a71-9a3e-2f6d1c7b5a10",
    "report_type": "custom_builder_v1",
    "schedule_type": "every_x",
    "interval_seconds": 604800,
    "report_name": "Weekly traffic",
    "destination_public_ids": ["f2a7c9e1-5d3b-4b80-9e6a-1c4d7f0b2e35"],
    "definition_json": {
      "version": "custom_builder.v1",
      "trigger": "scheduled",
      "sections": [
        { "id": "total_clicks", "order": 1, "settings": { "window": "7d" } },
        { "id": "top_links", "order": 2, "settings": { "top_n": 10 } }
      ],
      "options": { "include_comparison": true, "locale": "en-US" }
    }
  }'

The response is 201, with the new rule in data, as in Get a rule. If the rule’s details can’t be read back right away, data has only report_definition_id, delivery_rule_id, watch_id and next_run_at.

Older single-alert report_type values are still accepted for existing integrations. New integrations should use custom_builder_v1.

The definition

definition_json is an object with these fields:

FieldNotes
versioncustom_builder.v1.
triggerscheduled for a report, event for an alert.
sectionsA report’s sections, in order: {"id": ..., "order": 1, "settings": {...}}.
trigger_conditionsAn alert’s conditions, with the same shape. The alert fires when any of them is met (trigger_logic: or).
context_sectionsUp to 3 sections an alert adds after its trigger. Send settings as {}.
filters.tag_public_idsOnly cover links with these tags.
options.localeThe language the rule is written in: en-US, es-ES, cs-CZ, fr-FR or de-DE. Defaults to your profile language.
options.include_comparisonCompare with the previous period.
options.attach_csvAttach the report’s data to its emails as a CSV file. Reports only.

Report sections:

CategorySection IDs
Traffictotal_clicks, top_links, click_trend, peak_times, link_momentum, referrer_breakdown, utm_breakdown, qr_scans
Audiencegeo_breakdown, device_mix, language_mix, traffic_quality
Revenueconversions_summary, top_converting_links, commissions_summary, partner_payouts
Linkstag_performance, team_performance, inactive_links, ab_tests, link_activity, upcoming_links
Health & securityhealth_snapshot, quota_snapshot, abuse_reports, destination_security, domain_status, conversion_connectors
Workspaceworkspace_changes

Most sections take a window setting: 24h, 7d, 14d, 30d or 90d. Without it, a section reads the report’s interval. Ranked sections take top_n.

Alert conditions:

Condition IDSettings the dashboard starts with
link_click_threshold{"threshold": 1000, "recurring": true}
traffic_change{"direction": "increase", "window_minutes": 15, "change_percent": 100, "min_clicks": 20, "cooldown_minutes": 60}
unexpected_geo{"window_minutes": 30, "baseline_days": 7, "min_window_clicks": 20, "min_country_clicks": 5, "ignore_unknown": true, "cooldown_minutes": 180}
qr_scan_milestone{"threshold": 100, "recurring": true}
link_health_changed{"status_code_groups": ["4xx", "5xx"]}
link_expiration_warning{"warning_presets": [24]}
link_expired, link_status_changed, link_scheduled_live, link_destination_changed{}
link_abuse_reported{"review_outcomes": "none"}
bot_traffic_surge{"window_minutes": 60, "bot_share_percent": 50, "min_clicks": 50, "cooldown_minutes": 180}
link_conversion{"event_types": "sales", "cooldown_minutes": 0}
link_refund{"refunds": "all", "cooldown_minutes": 0}
commission_pending, conversion_connector_issue, ab_test_ready{}
workspace_usage_quota_alert{"active_links_percent": 80, "tracked_clicks_percent": 80, "repeat_interval": "once"}
workspace_domain_issue{"issues": "both"}
workspace_member_changed{"changes": "both"}

An alert definition:

{
  "version": "custom_builder.v1",
  "trigger": "event",
  "trigger_logic": "or",
  "trigger_conditions": [
    { "id": "link_click_threshold", "order": 1, "settings": { "threshold": 1000, "recurring": true } }
  ],
  "context_sections": [
    { "id": "top_links", "order": 1, "settings": {} }
  ],
  "options": { "locale": "en-US" }
}

Update a rule

PATCH changes what you send and keeps the rest. Send the fields as when creating.

  • Pause or resume: send only {"enabled": false} or {"enabled": true}. Resuming a rule checks your plan’s rule limit again.
  • New interval: a new interval_seconds without initial_run_at moves the next run to one new interval from now, unless the run already planned is sooner.
  • Destinations: the API returns destinations with their secrets shortened. To change them, send destination_public_ids, or leave destinations out to keep them. Sending a shortened value back returns 400 destination_secret_redacted.
  • Workspace: a rule can’t move to another workspace. Create a new rule there instead.
curl -X PATCH https://app.shortn.link/api/v1/reports/rules/e7b2c4a9-1f6d-4b38-9c0a-5d2e8f1b7a63 \
  -H "Authorization: Bearer $SHORTN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

The response is the rule in data, with the fields of List rules.

Delete a rule

curl -X DELETE https://app.shortn.link/api/v1/reports/rules/e7b2c4a9-1f6d-4b38-9c0a-5d2e8f1b7a63 \
  -H "Authorization: Bearer $SHORTN_API_KEY"

The response is 204 with no body.

Plan limits

Plan limits return 403 with code plan_limit_exceeded and feature report_alert_rules:

errorrequired_plan
Triggered alerts are available on the Starter plan or higherstarter
Free plan scheduled reports can run at most once per weekstarter
Report and alert rule limit reached for your current plannull, with limit and current

The limit counts the enabled rules you created; paused rules don’t count. A destination type your plan doesn’t include returns 403 with feature webhooks_integrations (see destinations).

Errors

StatuscodeWhen
400invalid_requestThe body isn’t valid JSON.
400workspace_requiredworkspace_public_id is missing.
400invalid_report_ruleThe reporting service refused the rule. error says why, for example interval_seconds is required.
400workspace_move_not_supportedThe update names another workspace.
400destination_secret_redactedA destination still holds a shortened secret.
403workspace_permission_deniedYou’re a read-only member.
403api_key_workspace_mismatchThe workspace or rule is outside the key’s workspace.
403plan_limit_exceededSee plan limits.
404workspace_not_foundThe workspace doesn’t exist, is archived, or you aren’t a member.
404report_rule_not_foundNo rule with this ID that you can see.
409workspace_archivedThe rule’s workspace is archived.
502report_delete_failedThe rule couldn’t be deleted. Try again.
503reports_unavailableThe reporting service is unavailable. Try again in a few minutes.

Errors every endpoint can return (a missing key, a missing scope, rate limits) are listed on authentication.

Last updated on