REST API endpoints

Endpoints

Events

Contains the same data as the main events feed.

• GET /wp-json/simple-history/v1/events
• GET /wp-json/simple-history/v1/events/has-updates
• GET /wp-json/simple-history/v1/events/aggregate – Count events instead of listing them. See Counting events below.
• GET /wp-json/simple-history/v1/events/<event-id>
• POST /wp-json/simple-history/v1/events/<event-id>/stick
• POST /wp-json/simple-history/v1/events/<event-id>/unstick
• POST /wp-json/simple-history/v1/events/<event-id>/react – Add a reaction to an event. Pass type: thumbsup, heart, smile, tada, eyes, rocket, clap or fire.
• POST /wp-json/simple-history/v1/events/<event-id>/unreact – Remove your reaction. Takes the same type.

Query Parameters for GET /events

The events endpoint supports various query parameters for filtering and pagination:

Basic Parameters

Parameter	Type	Description
per_page	int	Number of events per page (default: 10)
page	int	Page number for pagination (default: 1)
date_from	string	Show events from this date. A Unix timestamp, or a date like YYYY-MM-DD (read in the site’s timezone).
date_to	string	Show events up to this date. Same formats as date_from.
dates[]	array	A date range: lastdays:7 for the last 7 days, or month:2026-09 for a month.
lastdays	int	Show events from the last this many days.
months[]	array	Show events from these months, in YYYY-MM format.
search	string	Search for events containing this text
metadata_search	string	Search all event metadata (IP addresses, emails, user agents and so on). Slower than search.
ai_only	boolean	Show only events initiated via an AI tool, such as Claude Code or ChatGPT.
ip_address	string	Show only events from this IP address. Supports anonymized addresses ending in .x.
include_sticky	boolean	Include sticky events in the results.
only_sticky	boolean	Show only sticky events.
orderby	string	Column to sort by: date (default), id, level, logger or message (the event type). Sorting by anything other than date returns events ungrouped. Sorting by level orders by severity.
order	string	Sort direction: desc (default, newest first) or asc.

Inclusion Filters

Parameter	Type	Description
loggers[]	array	Include only events from these loggers
loglevels[]	array	Include only events with these log levels
messages[]	array	Include only specific message types (format: LoggerSlug:MessageKey)
user	int	Include only events by this user ID
users[]	array	Include only events by these user IDs
initiator	string	Include only events by this initiator type

Exclusion Filters (Negative Filters)

Use these parameters to exclude events matching specific criteria:

Parameter	Type	Description
exclude_loglevels[]	array	Exclude events with these log levels
exclude_loggers[]	array	Exclude events from these loggers
exclude_messages[]	array	Exclude specific message types (format: LoggerSlug:MessageKey)
exclude_users[]	array	Exclude events by these user IDs
exclude_initiator[]	array	Exclude events by these initiator types
exclude_search	string	Exclude events containing this text

Valid Initiator Values

• wp_user – Regular WordPress user actions
• wp_cli – Actions performed via WP-CLI
• wp – WordPress system actions (cron jobs, automatic updates)
• web_user – Non-logged-in web visitors
• other – Other sources

Example Requests

# Get events excluding debug level
curl -u user:app-password \
  'https://example.com/wp-json/simple-history/v1/events?exclude_loglevels[]=debug'

# Get events excluding WordPress system actions
curl -u user:app-password \
  'https://example.com/wp-json/simple-history/v1/events?exclude_initiator[]=wp'

# Get user events, excluding cron-related entries
curl -u user:app-password \
  'https://example.com/wp-json/simple-history/v1/events?initiator=wp_user&exclude_search=cron'

# Get events excluding multiple loggers
curl -u user:app-password \
  'https://example.com/wp-json/simple-history/v1/events?exclude_loggers[]=SimplePluginLogger&exclude_loggers[]=SimpleThemeLogger'

# Get the oldest events first
curl -u user:app-password \
  'https://example.com/wp-json/simple-history/v1/events?orderby=date&order=asc'

# Get the most serious events from the last 7 days first
curl -u user:app-password \
  'https://example.com/wp-json/simple-history/v1/events?dates[]=lastdays:7&orderby=level&order=desc'Code language: PHP (php)

Note: When the same value appears in both an inclusion and exclusion filter, exclusion takes precedence.

Counting events: GET /events/aggregate

Counts events instead of listing them. Use it to draw a chart, or to see how many events of each kind there are, without fetching every event. Added in Simple History 5.34.0.

It takes all the filters that GET /events takes, so it counts exactly the events the list would show. Paging parameters (page, per_page and offset) are not accepted. On top of the filters there are three parameters that decide how events are counted:

Parameter	Type	Description
group_by	string	What to count the events by: date (default), level, logger or initiator.
interval	string	Bucket size when counting by date: day (default) or hour.
split_by_level	boolean	Also split each bucket by log level. Default false.

The response is a list with one entry per bucket. Each entry has the bucket (a date, level, logger or initiator), the level (null unless split_by_level is on) and the count. Dates are in the site’s timezone. Buckets with no events are left out, so a day with no events is missing rather than 0.

# Events per day for the last 7 days
curl -u user:app-password \
  'https://example.com/wp-json/simple-history/v1/events/aggregate?dates[]=lastdays:7'

[
  {"bucket": "2026-09-22", "level": null, "count": 9},
  {"bucket": "2026-09-23", "level": null, "count": 89}
]

# Events per day, split by log level
curl -u user:app-password \
  'https://example.com/wp-json/simple-history/v1/events/aggregate?dates[]=lastdays:7&split_by_level=true'

[
  {"bucket": "2026-09-23", "level": "info", "count": 79},
  {"bucket": "2026-09-23", "level": "notice", "count": 8},
  {"bucket": "2026-09-23", "level": "warning", "count": 2}
]

# Events per hour today
curl -u user:app-password \
  'https://example.com/wp-json/simple-history/v1/events/aggregate?dates[]=lastdays:1&interval=hour'

# How many events each initiator caused
curl -u user:app-password \
  'https://example.com/wp-json/simple-history/v1/events/aggregate?group_by=initiator'

[
  {"bucket": "web_user", "level": null, "count": 112},
  {"bucket": "wp", "level": null, "count": 1411},
  {"bucket": "wp_user", "level": null, "count": 2537}
]

# Failed logins per day for the last 30 days
curl -u user:app-password \
  'https://example.com/wp-json/simple-history/v1/events/aggregate?dates[]=lastdays:30&loggers[]=SimpleUserLogger&loglevels[]=warning'Code language: PHP (php)

Stats

These endpoints contain the same data as the Premium add-on uses on the Stats and Summaries page/History insights page.

• /wp-json/simple-history/v1/stats/summary – Brief overview with total counts for events, users, content, media, plugins, and core updates
• /wp-json/simple-history/v1/stats/activity-overview – Daily activity breakdown
• /wp-json/simple-history/v1/stats/peak-days – High activity day analysis
• /wp-json/simple-history/v1/stats/peak-times – Peak activity time patterns
• /wp-json/simple-history/v1/stats/users – Detailed user activity insights
• /wp-json/simple-history/v1/stats/content – Content modification statistics
• /wp-json/simple-history/v1/stats/media – Media upload and management metrics
• /wp-json/simple-history/v1/stats/plugins – Plugin installation and update data
• /wp-json/simple-history/v1/stats/core – WordPress core update tracking
• /wp-json/simple-history/v1/stats/notes – Block editor notes activity (added/resolved counts, WordPress 6.9+)

Alerts (Premium)

These endpoints are available with the Simple History Premium add-on (1.9.0+). They require administrator permissions.

Destinations

Manage where alert notifications are sent (Email, Slack, Discord, Telegram).

• GET /wp-json/simple-history/v1/alerts/destinations – List all destinations
• POST /wp-json/simple-history/v1/alerts/destinations – Create a destination
• GET /wp-json/simple-history/v1/alerts/destinations/{id} – Get a single destination
• PUT /wp-json/simple-history/v1/alerts/destinations/{id} – Update a destination
• DELETE /wp-json/simple-history/v1/alerts/destinations/{id} – Delete a destination
• POST /wp-json/simple-history/v1/alerts/destinations/{id}/test – Send a test notification

Rules

Manage alert rules that define which events trigger notifications.

• GET /wp-json/simple-history/v1/alerts/rules – List all rules
• POST /wp-json/simple-history/v1/alerts/rules – Create a rule
• GET /wp-json/simple-history/v1/alerts/rules/{id} – Get a single rule
• PUT /wp-json/simple-history/v1/alerts/rules/{id} – Update a rule
• DELETE /wp-json/simple-history/v1/alerts/rules/{id} – Delete a rule
• GET /wp-json/simple-history/v1/alerts/rules/preview – Preview events matching rule conditions

Usage examples

• Monitor WordPress Activity from Your macOS Menu Bar with SwiftBar and Simple History