Hitting timeouts: help with API Headers for Prisma Cloud CSPM APIs

[sashank]

Describe the problem

The Prisma Cloud API docs for CSPM currently do not provide enough actionable guidance for timeout/rate-limit behavior in real-world usage of POST /v2/resource/scan_info, especially when users are already applying strong query narrowing and prefilter strategies.

We ran a sequence of reproducible API experiments (time-window narrowing, account scoping, cloud scoping, server-side filters, and vulnerability prefiltering via /uve/api/v1/vulnerabilities/search) and repeatedly hit request timeouts even at the narrowest practical scope (maxAssets=1).

From a docs perspective, it is unclear what additional API-side constraints/limits/usage patterns are recommended when this endpoint still times out after aggressive narrowing.

Describe the fix

Please add explicit troubleshooting and scaling guidance to PAN API docs (linked below), focused on scan_info and its interaction with rate limits/timeouts.

Suggested additions:

1. Clarify execution/cost model for POST /v2/resource/scan_info:

   • Whether server-side aggregation/work happens before page return
   • Whether pageSize affects backend compute load or only response size

2. Add timeout handling section for scan_info:

   • Recommended narrowing order (account, cloud type, absolute time windows, etc.)
   • Practical query shapes that are known to complete reliably on large tenants

3. Add clear filter-value semantics and validation examples:

   • cloud.account expected value format (display name vs provider-native account ID)
   • cloud.region and resource.type valid-value guidance and where to discover allowed values

4. Add guidance for combining endpoints:

   • Using /uve/api/v1/vulnerabilities/search to prefilter and then querying scan_info with unifiedAssetId
   • Expected limits/behavior when this still times out

5. Expand rate-limit guidance with endpoint-specific advice:

   • How to use X-RateLimit-Remaining, X-RateLimit-Replenish-Rate, Retry-After
   • Backoff recommendations specific to long-running/expensive endpoints like scan_info

6. Add representative error troubleshooting matrix:

   • 400 invalid filter/query
   • 429 rate limited
   • gateway/backend timeout behaviors

Where is the problem?

• https://pan.dev/prisma-cloud/api/cspm/api-headers/
• https://pan.dev/prisma-cloud/api/cspm/rate-limits/
• https://pan.dev/prisma-cloud/api/cspm/api-errors/
• https://pan.dev/prisma-cloud/api/cspm/vulnerabilities-search-api/
• (Related endpoint behavior context: CSPM resource/scan_info docs)

Additional context

Experiment summary (since yesterday):

• scan_info narrowing experiments across multiple windows/scopes commonly timed out at 120–180s.
• Region/resource-type variants often returned 400 when values were not accepted in that context.
• Vulnerability prefilter flow was tested with valid vulnerability RQL and progressively tighter limits.
• Even the narrowest end-to-end run (vulnerabilityPrefilterMaxAssets=1, 15m window, account-scoped) still timed out at 180s.

This issue is about documentation clarity and operational guidance for API consumers, not a request to change platform behavior.