Question about CloudCode API Hook and Global Property read costs / usage count

gyutaelee

Hello,

We are planning to use a CloudCode script.RUN API Pre-hook to enforce a client app version gate.

The flow is as follows:

The client calls ScriptService.RunScript once.
A script.RUN Pre-hook runs our Pre_VersionGate CloudCode script.
Inside Pre_VersionGate, we call bridge.getGlobalProperty("VERSION_POLICY") once.
If the policy allows the request, the original CloudCode script runs.
If the policy blocks the request, the Pre-hook returns 403 and the original script does not run.

We would like to confirm how this affects usage and billing.

Questions:

Does the script.RUN Pre-hook execution count as a separate CloudCode execution or API count in addition to the original RunScript call?
Does bridge.getGlobalProperty("VERSION_POLICY") inside the Pre-hook count as an API call / usage count?
The CloudCode documentation mentions that the first 3 API calls are free and each call after that counts as 1/2. Does this rule apply to API Hook CloudCode scripts as well?
In the normal pass-through case, how is the usage count calculated?
- 1 client RunScript call
- 1 Pre-hook execution
- 1 getGlobalProperty call inside the Pre-hook
- 1 original CloudCode script execution
In the blocked case, the original CloudCode script does not run. How is the usage count calculated in that case?
Could reading a Global Property on every script.RUN call become a performance or cost concern?
For a version policy that is read frequently but changed rarely, is there a recommended caching approach in BrainCloud?
Are there any Portal or usage report metrics where we can separately check the following?
- API Hook execution count
- CloudCode script execution count
- CloudCode internal API call count
- Global Property read count

We do not have an exact traffic estimate yet, so for now we would like to understand how usage count is calculated for this structure.

Thank you.

JasonL

Hi @gyutaelee ,

Based on the current brainCloud's implementation, here are the answers to your questions:

Q1: Does the Pre-hook count as a separate CloudCode execution / API count?**

Yes. The Pre-hook counts as both a separate API call and a separate CloudCode script invocation. After running, the server publishes its own analytics event with operation "RUN_HOOK-Pre_VersionGate" that increments both counts.

Q2: Does bridge.getGlobalProperty() count as an API call?**

No. bridge.getGlobalProperty() is completely free. It reads directly from the cached Game object in memory and bypasses the API call tracking pipeline entirely.

Q3: Does the "first 3 free, then 0.5 each" rule apply to hook CloudCode scripts?**

Yes, the discount applies to internal calls from any script or hook within the session.

Q4: Pass-through case: usage count breakdown

Client calls script.RUN: +1 API call
Pre-hook executes: +1 API call
bridge.getGlobalProperty() inside hook: free
Original CloudCode script: +0 (covered by the original script.RUN request)

Total external API count: 2

Q5: Blocked case: usage count breakdown

Client calls script.RUN: +1 API call
Pre-hook executes: +1 API call
bridge.getGlobalProperty() inside hook: 0 (free)
Original script: +0 (does not run, server throws before invoking it when hook returns non-200)

Total external API count: 2

The blocked case costs the same as pass-through from an API-count perspective. The only savings is that the original script's internal bridge.callAPI() calls are avoided.

Q6: Could reading a Global Property on every script.RUN become a performance or cost concern?

Performance: No. getGlobalProperty() reads from an in-memory cached Game object (ConcurrentHashMap per node) with no DB query or network call.

Cost: The hook itself adds +1 API count to every script.RUN call that has the hook attached.

Q7: Recommended caching approach for frequently-read, rarely-changed property?

The cache is already in place, no additional caching needed. brainCloud stores the Game object (including all global properties) in an in-memory cache for each server node. Cross-node invalidation is handled automatically when a global property is updated in the portal. Using bridge.getGlobalProperty() is already the optimal pattern.

Q8: Portal metrics: what can be broken down separately?

API Hook execution count: Partially available. Hooks appear within the CC script invocation counter; no hook-only counter exists.
CloudCode script execution count: Available as CC Script Invocations, but includes hooks in the same counter.
CloudCode internal API call count: Available as CC API Calls in the Monitoring dashboard.
Global Property read count: Not tracked. No metric exists for this.

Paul Winterhalder

I should clarify - the first 2 api calls are free in a script - not the first 3.

Where did you see the document with 3? [That is old - from several years ago]

gyutaelee

Hi @JasonL and @Paul-Winterhalder ,

Thank you both for the detailed clarification.

We now understand the usage calculation as follows:

The client script.RUN call counts as +1 API count.
The script.RUN Pre-hook execution counts as an additional +1 API count / CloudCode invocation.
bridge.getGlobalProperty() does not count as an API call because it reads from the cached Game object.
The original CloudCode script execution is covered by the original script.RUN request.
Therefore, both the pass-through and blocked cases count as 2 API counts before considering any internal bridge.callAPI() calls from the original script.

Also, thank you for correcting the CloudCode internal API call rule. We will treat the current rule as “the first 2 API calls are free in a script, and every call after that is 1/2 API count,” not “first 3 free.”

One follow-up question:

If a script.RUN request has a Pre-hook and then the original CloudCode script runs, how is the “first 2 API calls are free” rule applied to internal bridge.callAPI() calls?

Is the free-call allowance applied separately per CloudCode script invocation, for example:

Pre-hook CloudCode script: first 2 internal API calls are free
Original CloudCode script: first 2 internal API calls are free

Or is the allowance shared across the whole request/session chain, including both the Pre-hook and the original CloudCode script?

For our current version-gate Pre-hook, we only call bridge.getGlobalProperty(), so this does not affect that hook directly. However, we would like to understand the calculation correctly in case the Pre-hook or the original script uses bridge.callAPI() in the future.

Regarding the “first 3 API calls are free” reference, I may have seen it in an older document or cached/search result. I will try to find the exact source and share it if I can locate it.

Thanks again.