Skip to main content
POST
devices.events.search

Authorizations

Authorization
string
header
required

API key: sk_live_…

Headers

Idempotency-Key
string

Optional. A retry with the same key returns the stored result.

Maximum string length: 255
Pramaan-Account
string

Optional. One of your account ids (GET /v1/accounts): run on that account, whatever your routing rules say. The response header X-Pramaan-Account names the account that ran.

Pramaan-End-User
string

Optional. Your own tag for your end user: a sticky: end_user rule keeps them on the account that first served them.

Maximum string length: 256
Pramaan-End-User-Group
string

Optional. Your end user's group, matched by rules with endUserGroup.

Maximum string length: 64

Body

application/json
ref
string

The ref returned by a visitor row of devices.visitors.list or devices.events.search.

Pattern: ^(ref_[0-9A-HJKMNP-TV-Z]{26}|rh_[A-Za-z0-9_-]{24,1024})$
source
enum<string>
default:device

Collection source; default device.

Available options:
device,
edge
limit
number

Page size, 1 to 50; default 10.

Required range: x >= 1
cursor
string

Opaque nextCursor from the same query.

Required string length: 1 - 4096
start
string<date-time>

UTC time in ISO 8601 format.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
end
string<date-time>

UTC time in ISO 8601 format.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
oldestFirst
boolean

Return oldest observations first.

includeDeviceAttributes
boolean
default:false

Include detailed browser/device attributes; default off. Requires account access.

includeLabels
boolean
default:false

Include custom device-observation labels; default off. Requires account access.

bot
enum<string>

Exact bot filter; omitted means no filter.

Available options:
all,
good,
bad,
none
botInformation
enum<string>

Exact botInformation filter; omitted means no filter.

Available options:
all,
none
botCategories
enum<string>[]

Exact botCategories filter; omitted means no filter.

Maximum array length: 100
Available options:
advertising_and_marketing,
aggregator,
ai_agent,
ai_assistant,
ai_browser,
ai_crawler,
ai_search,
browser_automation,
ecommerce,
monitoring_and_analytics,
other,
scraping,
security,
search_engine_crawler,
search_engine_optimization,
unknown
botIdentities
enum<string>[]

Exact botIdentities filter; omitted means no filter.

Maximum array length: 100
Available options:
verified,
signed,
spoofed,
unknown
botConfidences
enum<string>[]

Exact botConfidences filter; omitted means no filter.

Maximum array length: 100
Available options:
low,
medium,
high
botOperators
string[]

Exact botOperators filter; omitted means no filter.

Maximum array length: 100
Maximum string length: 5000
botNames
string[]

Exact botNames filter; omitted means no filter.

Maximum array length: 100
Maximum string length: 5000
ip
string

Exact ip filter; omitted means no filter.

Maximum string length: 64
autonomousSystem
string

Exact autonomousSystem filter; omitted means no filter.

Maximum string length: 5000
linkedId
string

Exact linkedId filter; omitted means no filter.

Maximum string length: 5000
url
string

Exact url filter; omitted means no filter.

appBundle
string

Exact appBundle filter; omitted means no filter.

Maximum string length: 5000
appPackage
string

Exact appPackage filter; omitted means no filter.

Maximum string length: 5000
origin
string

Exact origin filter; omitted means no filter.

suspect
boolean

Exact suspect filter; omitted means no filter.

vpn
boolean

Exact vpn filter; omitted means no filter.

virtualMachine
boolean

Exact virtualMachine filter; omitted means no filter.

tampering
boolean

Exact tampering filter; omitted means no filter.

antiDetectBrowser
boolean

Exact antiDetectBrowser filter; omitted means no filter.

incognito
boolean

Exact incognito filter; omitted means no filter.

privacySettings
boolean

Exact privacySettings filter; omitted means no filter.

jailbroken
boolean

Exact jailbroken filter; omitted means no filter.

instrumentation
boolean

Exact instrumentation filter; omitted means no filter.

factoryReset
boolean

Exact factoryReset filter; omitted means no filter.

clonedApp
boolean

Exact clonedApp filter; omitted means no filter.

emulator
boolean

Exact emulator filter; omitted means no filter.

rootApps
boolean

Exact rootApps filter; omitted means no filter.

vpnConfidence
enum<string>

Exact vpnConfidence filter; omitted means no filter.

Available options:
high,
medium,
low
minSuspectScore
number

Exact minSuspectScore filter; omitted means no filter.

developerTools
boolean

Exact developerTools filter; omitted means no filter.

locationSpoofing
boolean

Exact locationSpoofing filter; omitted means no filter.

mitmAttack
boolean

Exact mitmAttack filter; omitted means no filter.

rareDevice
boolean

Exact rareDevice filter; omitted means no filter.

rareDevicePercentileBucket
enum<string>

Exact rareDevicePercentileBucket filter; omitted means no filter.

Available options:
<p95,
p95-p99,
p99-p99.5,
p99.5-p99.9,
p99.9+,
not_seen
proxy
boolean

Exact proxy filter; omitted means no filter.

collectorVersion
string

Exact collectorVersion filter; omitted means no filter.

Maximum string length: 5000
collectorPlatform
enum<string>

Exact collectorPlatform filter; omitted means no filter.

Available options:
js,
android,
ios
torNode
boolean

Exact torNode filter; omitted means no filter.

incrementalIdentificationStatus
enum<string>

Exact incrementalIdentificationStatus filter; omitted means no filter.

Available options:
partially_completed,
completed
simulator
boolean

Exact simulator filter; omitted means no filter.

activeCall
boolean

Exact activeCall filter; omitted means no filter.

Response

The result

results
object[]
required

Matching observations or resources.

nextCursor
string

Opaque cursor for the next page.

Required string length: 1 - 4096