Execute a declarative query using the powerful PulseQuery builder

This endpoint provides a more structured and powerful alternative to text-based search, allowing complex filtering, aggregation, and business logic queries.

Examples:

Find all activities by specific agents in last 7 days

{ “agent_types”: [“user”], “last_days”: 7, “sort_by”: “time” }

Customer journey analysis

{ “customer_id”: “customer_123”, “last_days”: 30, “sort_by”: “time”, “sort_direction”: “asc” }

Revenue impact events with duration filters

{ “revenue_impact”: true, “min_duration_minutes”: 5, “tags”: [“sales”, “deal”], “tag_mode”: “all” }

Aggregated metrics by team

{ “last_days”: 14, “aggregate”: true, “group_by”: [“agent_type”], “team_name”: “engineering” }

Execute a declarative query using the powerful PulseQuery builder This endpoint provides a more structured and powerful alternative to text-based search, allowing complex filtering, aggregation, and business logic queries. Examples: # Find all activities by specific agents in last 7 days { "agent_types": ["user"], "last_days": 7, "sort_by": "time" } # Customer journey analysis { "customer_id": "customer_123", "last_days": 30, "sort_by": "time", "sort_direction": "asc" } # Revenue impact events with duration filters { "revenue_impact": true, "min_duration_minutes": 5, "tags": ["sales", "deal"], "tag_mode": "all" } # Aggregated metrics by team { "last_days": 14, "aggregate": true, "group_by": ["agent_type"], "team_name": "engineering" }

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

limitintegerOptional>=1<=1000Defaults to 50

Maximum results to return

offsetintegerOptional>=0Defaults to 0

Offset for pagination

text_querystring or nullOptional

Text to search in descriptions

time_range_startstring or nullOptionalformat: "date-time"

Start time for filtering

time_range_endstring or nullOptionalformat: "date-time"

End time for filtering

last_hoursinteger or nullOptional>=1

Filter to last N hours

last_daysinteger or nullOptional>=1

Filter to last N days

agent_typeslist of stringsOptional

Filter by agent types

agent_idslist of stringsOptional

Filter by specific agent IDs

object_typeslist of stringsOptional

Filter by object types

object_idslist of stringsOptional

Filter by specific object IDs

action_typeslist of stringsOptional

Filter by action types

action_statuseslist of stringsOptional

Filter by action statuses

specific_actionslist of stringsOptional

Filter by specific action names

tagslist of stringsOptional

Tags to include

exclude_tagslist of stringsOptional

Tags to exclude

tag_modeenumOptionalDefaults to any

Whether to match any or all tags

Allowed values:

min_duration_minutesdouble or nullOptional

Minimum duration in minutes

max_duration_minutesdouble or nullOptional

Maximum duration in minutes

customer_idstring or nullOptional

Filter by customer ID

team_namestring or nullOptional

Filter by team

deal_stageslist of stringsOptional

Filter by deal stages

revenue_impactbooleanOptionalDefaults to false

Filter for revenue impact events

churn_riskbooleanOptionalDefaults to false

Filter for churn risk events

escalation_levelstring or nullOptional

Filter by escalation level

trace_idstring or nullOptional

Filter by trace ID

triggered_bystring or nullOptional

Filter by triggering event

sort_byenumOptionalDefaults to time

Sort field

Allowed values:

sort_directionenumOptionalDefaults to desc

Sort direction

Allowed values:

count_onlybooleanOptionalDefaults to false

Return only count, not full results

explainbooleanOptionalDefaults to false

Include query explanation

aggregatebooleanOptionalDefaults to false

Return aggregated results

group_bylist of enumsOptional

Group by fields for aggregation

group_by_tag_prefixstring or nullOptional

Group by tag prefix (e.g., ‘customer:’)

Response

Successful Response

Errors

Execute a declarative query using the powerful PulseQuery builder

This endpoint provides a more structured and powerful alternative to text-based search, allowing complex filtering, aggregation, and business logic queries.

Examples:

Find all activities by specific agents in last 7 days

{ “agent_types”: [“user”], “last_days”: 7, “sort_by”: “time” }

Customer journey analysis

{ “customer_id”: “customer_123”, “last_days”: 30, “sort_by”: “time”, “sort_direction”: “asc” }

Revenue impact events with duration filters

{ “revenue_impact”: true, “min_duration_minutes”: 5, “tags”: [“sales”, “deal”], “tag_mode”: “all” }

Aggregated metrics by team

{ “last_days”: 14, “aggregate”: true, “group_by”: [“agent_type”], “team_name”: “engineering” }

1	import requests
2
3	url = "https://api-prod.scoutos.com/pulse/query"
4
5	payload = {}
6	headers = {
7	"Authorization": "Bearer <token>",
8	"Content-Type": "application/json"
9	}
10
11	response = requests.post(url, json=payload, headers=headers)
12
13	print(response.json())