Admin API Docs Missing includedSpendCents and New Teams Usage Metrics

Support Bug Reports
,
1

Where does the bug appear (feature/product)?

Somewhere else…

Describe the Bug

Summary

The Teams Admin API documentation for “Get Spending Data” appears to be outdated and does not match the actual response returned by POST /teams/spendCurrent.

This is particularly noticeable after the introduction of separate included usage pools for Composer, Auto, and Third-Party API usage.

Documentation

The current documentation shows teamMemberSpend objects with fields such as:

{
  "userId": 12345,
  "spendCents": 2450.125487,
  "overallSpendCents": 2450.125487,
  "fastPremiumRequests": 1250,
  "name": "Alex",
  "email": "[email protected]",
  "role": "member",
  "hardLimitOverrideDollars": 100,
  "monthlyLimitDollars": 200
}

Actual API Response

The actual POST /teams/spend response contains additional fields that are not documented, for example:

{
  "userId": "x",
  "spendCents": 0,
  "includedSpendCents": 84.29665,
  "fastPremiumRequests": 0,
  "name": "Alex",
  "email": "[email protected]",
  "profilePictureUrl": null,
  "role": "member",
  "monthlyLimitDollars": null,
  "hardLimitOverrideDollars": 0,
  "billingTier": "TIER_1000",
  "autoPercentUsed": 1.2,
  "apiPercentUsed": 0,
  "totalPercentUsed": 0.7636363636363637
}

Missing / Undocumented Fields

The documentation appears to be missing several fields currently returned by the API, including:

  • includedSpendCents
  • profilePictureUrl
  • billingTier
  • autoPercentUsed
  • apiPercentUsed
  • totalPercentUsed

Additionally, the documented field overallSpendCents does not appear in the current response.

Request

Could the Teams Admin API documentation be updated to reflect the current response schema and the newer included usage pool model? This would help developers accurately consume the API and avoid relying on outdated field definitions.

Steps to Reproduce

curl -X POST https://api.cursor.com/teams/spend \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "searchTerm": "[email protected]",
    "page": 2,
    "pageSize": 25
  }'

Operating System

MacOS

Version Information

Additional Information

Does this stop you from using Cursor

No - Cursor works, but with this issue

5

Hey, thanks for the detailed report. You’re right, the docs for Get Spending Data are behind the current API schema. The includedSpendCents, profilePictureUrl, billingTier, autoPercentUsed, apiPercentUsed, and totalPercentUsed fields aren’t documented right now, and I’ve sent this over so the docs can be updated.

A couple quick notes to help in the meantime:

  • billingTier, autoPercentUsed, apiPercentUsed, and totalPercentUsed are only populated for tiered self-serve teams. For non-tiered teams they’ll be undefined and omitted from the JSON, and that’s expected.
  • About overallSpendCents, I see it in the docs, but it’s missing in the actual response you got. We’ll look into why it isn’t being returned and update the docs to match the real API behavior.

I can’t share an ETA for the docs update yet, but it’s flagged. If you notice any other mismatches, please let me know.

9

Hey @keshav-k3, and sorry for the slow follow-up. I want to close out the question about overallSpendCents that was left over from last time.

overallSpendCents and includedSpendCents depend on the team’s plan. Teams on pooled usage get overallSpendCents, which is the member’s total usage for the billing cycle. Teams with a per-member included allowance instead get includedSpendCents usage within the included quota plus spendCents on-demand. So the response you shared is what we expect for this team’s plan, it’s not a missing value.

The other fields you listed profilePictureUrl, billingTier, autoPercentUsed, apiPercentUsed, totalPercentUsed are real response fields and you can rely on them. As mentioned earlier, billingTier and the percent fields only show up for teams on tiered self-serve pricing. For other teams they’re simply omitted from the JSON.

On the docs, there’s still a mismatch with the schema. I’ve passed this along so the page can be updated to match the real API response. I can’t share an ETA yet. If you notice any other mismatches in the response, let me know.