Batch API - Scheduler
Automate recurring exports. The Scheduler turns any Batch API report into a subscription that runs on its own — automatically, on every fresh data release — and notifies you the moment results are ready. No manual re-runs.
What you schedule is a Batch API report.
A subscription stores a normal Batch API report request — standard or Elastic — and runs it on your schedule. Anything you can export with the Batch API, you can put on a subscription.
Quickstart
1
Validate your report
POST your report to /subscriptions/validate to confirm it is valid — and pick the right schedule event — before you create anything.
2
Create the subscription
POST to /subscriptions/create with your report payload, a schedule event, and notification channels. You get back a subscription_id.
3
Let it run
On each data release, the scheduler runs your report with $date resolved to the latest available date, then fires your notifications.
4
Track every run
Call /subscriptions/:id/runs to see each execution and its status — running, completed, or failed.
Core concepts
Subscription
A saved recurring job: a Batch API report payload, a schedule, and notification channels.
Run
One execution of a subscription. Each run is running, completed, or failed.
Event
What triggers a run — a data-release event that fires whenever Similarweb publishes fresh data for your report's dataset.
Notifications
Webhook and/or email channels that tell you when a run completes, fails, or is expiring.
Authentication
Authenticate with your Batch API key in the api-key header. Every request is scoped to your account — you only ever see or change your own subscriptions.
https://api.similarweb.com/batch/v5/schedule
Operations
Create Subscription | POST | /subscriptions/create |
Validate Subscription | POST | /subscriptions/validate |
List Subscriptions | GET | /subscriptions |
Get Subscription | GET | /subscriptions/: |
Get Subscription Runs | GET | /subscriptions/: |
Update Subscription | POST | /subscriptions/: |
Enable / Disable | PUT | /subscriptions/: |
Renew Subscription | PUT | /subscriptions/: |
Retry Subscription Run | POST | /subscriptions/: |
FAQ
Why isn't my subscription running? | Check that it is enabled (not disabled or frozen), that its expiration date is in the future, and that the chosen event is valid for your report's dataset. If the event isn't valid for your query, the API returns the allowed set so you can correct it. |
How are credits charged for scheduled reports? | Each run is charged like a normal Batch API report — including the Elastic surcharge when the subscription uses an Elastic app. Validate first to estimate the per-run cost. |
How do I change the schedule or the report? | Use Update Subscription to change the report payload, event, or notifications. Use Renew Subscription to extend the expiration date — update cannot change it. |
Need help?
If you have any questions about scheduling reports, reach out to your Similarweb account manager.
Endpoints
batch/v5/schedule/subscriptions/create
batch/v5/schedule/subscriptions/validate
batch/v5/schedule/subscriptions/{subscription_id}/update
batch/v5/schedule/subscriptions?status=enabled&limit=1000&offset=0
batch/v5/schedule/subscriptions/{subscription_id}
batch/v5/schedule/subscriptions/{subscription_id}/runs?status=all
batch/v5/schedule/subscriptions/{subscription_id}/retry
batch/v5/schedule/subscriptions/{subscription_id}/enable
batch/v5/schedule/subscriptions/{subscription_id}/disable
batch/v5/schedule/subscriptions/{subscription_id}/renew