Logs & Analytics

Stream provides APIs to query moderation logs, export them for compliance, retrieve analytics, and track usage statistics. These endpoints help you audit moderation activity, monitor moderator performance, and generate reports.

Query Moderation Logs

POST /api/v2/moderation/logs

Query moderation action logs with filtering, sorting, and pagination. Logs record every moderation action taken -- who did what, when, and on which content.

response = client.moderation().query_moderation_logs(
    filter={"entity_type": "stream:chat:v1:message"},
    sort=[{"field": "created_at", "direction": -1}],
    limit=50,
)

Request Parameters

Key	Required	Type	Description
filter	false	object	Filter conditions for logs.
sort	false	array	Sort parameters (e.g., by `created_at`).
limit	false	number	Maximum number of logs to return.
next	false	string	Cursor for pagination.

Response

Key	Type	Description
logs	array	List of moderation log entries. Each entry includes action type, actor, target, timestamp, and details.
next	string	Next cursor for pagination.

Export Moderation Logs

POST /api/v2/moderation/logs/export

Export moderation logs for external analysis or compliance purposes. The export can be filtered by time range, entity type, or any other supported filter condition.

response = client.moderation().export_moderation_logs(
    filter={"created_at": {"$gte": "2024-01-01T00:00:00Z"}},
)

Request Parameters

Key	Required	Type	Description
filter	false	object	Filter conditions for which logs to export.

Response

Key	Type	Description
export_url	string	URL to download the exported logs file.
status	string	Status of the export operation.

Get Moderation Analytics

POST /api/v2/moderation/analytics

Retrieve moderation analytics for a specified time range. This is a server-side only endpoint that returns aggregate statistics about moderation activity.

response = client.moderation().get_moderation_analytics(
    from_="2024-01-01T00:00:00Z",
    to="2024-01-31T23:59:59Z",
)

Request Parameters

Key	Required	Type	Description
from	false	string	Start of time range (ISO 8601 datetime).
to	false	string	End of time range (ISO 8601 datetime).

Response

Key	Type	Description
analytics	object	Aggregate moderation analytics data for the specified time range.

Query Usage Stats

POST /api/v2/moderation/usage_stats

Query moderation usage statistics -- number of checks, flags, actions, and other operational metrics over a given time period.

response = client.moderation().query_usage_stats(
    from_="2024-01-01T00:00:00Z",
    to="2024-01-31T23:59:59Z",
)

Request Parameters

Key	Required	Type	Description
from	false	string	Start of time range (ISO 8601 datetime).
to	false	string	End of time range (ISO 8601 datetime).

Response

Key	Type	Description
stats	object	Usage statistics including counts for checks, flags, and actions within the time range.

Get User Moderation Report

GET /api/v2/moderation/user_report

Retrieve a comprehensive moderation report for a specific user, including moderation history, flags received, and actions taken against their content.

response = client.moderation().get_user_moderation_report(
    user_id="user_123",
)

Request Parameters

Key	Required	Type	Description
user_id	true	string	The ID of the user to get the report for.

Response

Key	Type	Description
report	object	Comprehensive moderation report for the user, including history, flags, and actions.

Get Flag Count

POST /api/v2/moderation/flag_count

Get the number of moderation flags created against a specific user's content. Useful for building moderation dashboards and identifying repeat offenders.

response = client.moderation().get_flag_count(
    user_id="user_123",
)

Request Parameters

Key	Required	Type	Description
user_id	true	string	User ID to get flag count for.
entity_type	false	string	Optionally filter by entity type.

Response

Key	Type	Description
count	number	Total number of flags for the specified user.