Salesforce Composite API Capabilities & Subrequest Limits

TL;DR

• Bottom line: Salesforce offers four composite resource types — Composite (25 subrequests with reference chaining), Composite Graph (500 subrequests with per-graph transactions), Composite Batch (25 independent subrequests), and sObject Collections (200 records per DML). Choose based on whether you need cross-subrequest references, all-or-nothing behavior, or maximum throughput.
• Key limit: Composite API caps at 25 subrequests (max 5 queries/collections); Composite Graph scales to 500 but each graph is its own transaction. The entire composite call counts as 1 API call against daily limits.
• Watch out for: Governor limits (100 SOQL queries, 150 DML statements, 10,000ms CPU) apply cumulatively across ALL subrequests in a single composite call — exceeding any governor limit aborts the entire request.
• Best for: Multi-step create/update workflows requiring atomicity (e.g., create Account + Contact + Opportunity in one call), or reducing API call consumption when creating related records.
• Authentication: OAuth 2.0 JWT bearer flow for server-to-server; web server flow for user-context. All composite resources require the same auth as standard REST API.

System Profile

This card covers all four Salesforce REST API composite resource types: Composite, Composite Graph, Composite Batch, and sObject Collections/Tree. These resources allow combining multiple REST API operations into a single HTTP call, reducing round trips and API call consumption. Available in API v43.0+ for sObject Collections and v50.0+ for Composite Graph. All editions that support REST API support composite resources, but API call daily limits vary significantly by edition.

API Surfaces & Capabilities

Salesforce provides four distinct composite resource types, each optimized for different integration patterns. The key differentiator is whether subrequests can reference each other's outputs and whether failures trigger full rollback.

Rate Limits & Quotas

Per-Request Limits

Rolling / Daily Limits

Transaction / Governor Limits

Governor limits apply cumulatively across all subrequests within a single composite call. This is the most common source of composite API failures.

Authentication

All composite resources use the same authentication as standard Salesforce REST API. No special scopes or permissions required beyond standard API access.

Authentication Gotchas

• Connected App creation is disabled by default in Spring '26 (v66.0). Admins must explicitly enable it or migrate to External Client App feature. [src8]
• All subrequests execute in the context of the same user session — permission checks apply per-subrequest but the token is shared. [src1]
• Legacy hostname redirects were removed in Spring '26 — use My Domain URLs exclusively. [src8]

Constraints

• 25-subrequest ceiling on Composite API — cannot be increased. If you need more, use Composite Graph (500) or split into multiple requests.
• 5 query/collection cap within Composite — only 5 of the 25 subrequests can be queries or sObject Collections operations.
• Governor limits are cumulative — all subrequests share one governor context. 25 subrequests each doing 5 SOQL queries = 125 total, exceeding the 100-query sync limit.
• Composite Graph graphs are independent — reference IDs cannot cross graph boundaries. Each graph is its own transaction.
• sObject Collections limited to 200 records — for volumes above 200, use multiple Collections calls or switch to Bulk API 2.0.
• sObject Tree is always all-or-nothing — no partial success mode. If any record fails, the entire tree is rolled back.
• API versions 21.0-30.0 retired — minimum supported version is v31.0 as of June 2025.

Integration Pattern Decision Tree

START — Need to combine multiple Salesforce REST operations into one call
├── Do subrequests need to reference each other's output?
│   ├── YES — need reference IDs
│   │   ├── Need ≤25 subrequests? → Composite API (allOrNone=true for atomicity)
│   │   └── Need >25 subrequests? → Composite Graph API (up to 500 per graph)
│   └── NO — subrequests are independent
│       ├── All DML on same object type? → sObject Collections (200 max)
│       ├── Creating parent-child hierarchies? → sObject Tree (200 max)
│       └── Mixed independent operations? → Composite Batch (25 max)
├── Volume check
│   ├── ≤200 records of same type → sObject Collections
│   ├── ≤200 records with parent-child → sObject Tree
│   ├── ≤25 mixed operations with refs → Composite API
│   ├── ≤500 operations with refs → Composite Graph
│   └── >500 records → Bulk API 2.0
└── Error handling preference
    ├── All-or-nothing required → Composite (allOrNone=true), Graph, or Tree
    ├── Partial success OK → Batch or Collections (allOrNone=false)
    └── Per-group atomicity → Composite Graph (each graph is atomic)

Quick Reference

Step-by-Step Integration Guide

1. Authenticate and obtain access token

Use OAuth 2.0 JWT bearer flow for server-to-server integrations. [src1]

# Input:  Connected App consumer key, private key, username
# Output: Access token and instance URL

curl -X POST https://login.salesforce.com/services/oauth2/token \
  -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
  -d "assertion=$(generate_jwt_assertion)"

Verify: Response contains access_token and instance_url fields. HTTP 200 = success.

2. Execute a Composite request with reference IDs

Create an Account and linked Contact in a single atomic call. [src1, src4]

curl -X POST https://{instance_url}/services/data/v66.0/composite \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "allOrNone": true,
    "collateSubrequests": true,
    "compositeRequest": [
      {
        "method": "POST",
        "url": "/services/data/v66.0/sobjects/Account",
        "referenceId": "refAccount",
        "body": {"Name": "Acme Corp", "Industry": "Technology"}
      },
      {
        "method": "POST",
        "url": "/services/data/v66.0/sobjects/Contact",
        "referenceId": "refContact",
        "body": {
          "FirstName": "Jane", "LastName": "Doe",
          "AccountId": "@{refAccount.id}"
        }
      }
    ]
  }'

Verify: Response HTTP 200 with compositeResponse array. Each element has httpStatusCode: 200.

3. Execute a Composite Graph request

Use Composite Graph for >25 subrequests or multiple independent transactional groups. [src2, src3]

curl -X POST https://{instance_url}/services/data/v66.0/composite/graph \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "graphs": [
      {
        "graphId": "graph1",
        "compositeRequest": [
          {"method": "POST", "url": "/services/data/v66.0/sobjects/Account",
           "referenceId": "ref1Acct", "body": {"Name": "Graph1 Corp"}},
          {"method": "POST", "url": "/services/data/v66.0/sobjects/Contact",
           "referenceId": "ref1Cont", "body": {"LastName": "Smith", "AccountId": "@{ref1Acct.id}"}}
        ]
      },
      {
        "graphId": "graph2",
        "compositeRequest": [
          {"method": "POST", "url": "/services/data/v66.0/sobjects/Account",
           "referenceId": "ref2Acct", "body": {"Name": "Graph2 Inc"}}
        ]
      }
    ]
  }'

Verify: Response graphs array. Each graph has isSuccessful: true/false. If graph1 fails, graph2 can still succeed.

4. Use sObject Collections for bulk DML

Batch create up to 200 records of the same sObject type. [src5]

curl -X POST https://{instance_url}/services/data/v66.0/composite/sobjects \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "allOrNone": false,
    "records": [
      {"attributes": {"type": "Contact"}, "FirstName": "Alice", "LastName": "Johnson"},
      {"attributes": {"type": "Contact"}, "FirstName": "Bob", "LastName": "Williams"}
    ]
  }'

Verify: Response is array of SaveResult: [{"id": "003xx...", "success": true, "errors": []}, ...]

Code Examples

Python: Composite request with reference IDs

# Input:  Salesforce access token, instance URL
# Output: Created Account ID and linked Contact ID

import requests  # requests>=2.31.0

def composite_create(instance_url, access_token):
    """Create Account + Contact atomically via Composite API."""
    url = f"{instance_url}/services/data/v66.0/composite"
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }
    payload = {
        "allOrNone": True,
        "collateSubrequests": True,
        "compositeRequest": [
            {
                "method": "POST",
                "url": "/services/data/v66.0/sobjects/Account",
                "referenceId": "refAccount",
                "body": {"Name": "Acme Corp"}
            },
            {
                "method": "POST",
                "url": "/services/data/v66.0/sobjects/Contact",
                "referenceId": "refContact",
                "body": {
                    "LastName": "Doe",
                    "AccountId": "@{refAccount.id}"
                }
            }
        ]
    }
    resp = requests.post(url, json=payload, headers=headers)
    resp.raise_for_status()
    results = resp.json()["compositeResponse"]
    return {r["referenceId"]: r["body"]["id"] for r in results}

JavaScript/Node.js: sObject Collections bulk upsert

// Input:  jsforce connection, array of records, external ID field
// Output: Array of SaveResult objects

const jsforce = require("jsforce"); // [email protected]

async function bulkCollectionsUpsert(conn, records, externalIdField) {
  const CHUNK_SIZE = 200; // sObject Collections max
  const results = [];
  for (let i = 0; i < records.length; i += CHUNK_SIZE) {
    const chunk = records.slice(i, i + CHUNK_SIZE);
    const res = await conn.requestPost(
      `/services/data/v66.0/composite/sobjects/${externalIdField}`,
      { allOrNone: false, records: chunk }
    );
    results.push(...res);
  }
  return results; // [{id, success, errors, created}, ...]
}

cURL: Composite Batch for independent queries

# Input:  Access token, instance URL
# Output: Array of independent results

curl -X POST https://{instance_url}/services/data/v66.0/composite/batch \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "batchRequests": [
      {"method": "GET", "url": "v66.0/sobjects/Account/describe"},
      {"method": "GET", "url": "v66.0/query?q=SELECT+Id,Name+FROM+Account+LIMIT+5"}
    ]
  }'
# Response: {"hasErrors": false, "results": [{statusCode: 200, result: {...}}, ...]}

Data Mapping

Reference ID Syntax

Data Type Gotchas

• Reference IDs must contain only alphanumeric characters and underscores — no hyphens, dots, or special characters. [src1]
• The @{refId.field} notation uses JavaScript-like dot syntax but does NOT support complex expressions or transformations. [src6]
• When collateSubrequests=true, the API may reorder independent subrequests to bulkify DML — do not rely on execution order for non-dependent subrequests. [src1]
• sObject Collections allOrNone=false returns HTTP 200 even if individual records failed — check each SaveResult's success field. [src4]

Error Handling & Failure Points

Common Error Codes

Failure Points in Production

• Governor limit breach from trigger cascading: Each subrequest fires triggers consuming shared governor context. 25 inserts x 5 SOQL per trigger = 125 queries, exceeding 100-query limit. Fix: audit triggers with Limits class; reduce SOQL per trigger. [src5]
• allOrNone=true with validation rules: One record failing validation rolls back ALL records. Fix: pre-validate data client-side before sending composite request. [src4]
• Cross-graph reference attempt: Reference IDs scoped to graph — @{ref1.id} from graph1 not accessible in graph2. Fix: design each graph as self-contained unit. [src2]
• sObject Tree exceeding 5-level depth: Max 5 levels (root + 4 children). Fix: flatten hierarchy or use Composite API with reference IDs. [src6]
• collateSubrequests reordering: API may reorder independent subrequests. Fix: use explicit reference IDs; set collateSubrequests=false if order matters. [src1]
• Session timeout during large Composite Graph: 500-subrequest graphs can timeout. Fix: ensure session timeout ≥30 min; use idempotent operations. [src2]

Anti-Patterns

Wrong: Making 25 individual API calls instead of 1 composite call

# BAD — 25 API calls consumed, 25 round trips
for record in records[:25]:
    requests.post(f"{url}/sobjects/Contact", json=record, headers=headers)

Correct: Bundle into a single Composite or Collections call

# GOOD — 1 API call consumed, 1 round trip
payload = {
    "allOrNone": False,
    "records": [{"attributes": {"type": "Contact"}, **r} for r in records[:200]]
}
requests.post(f"{url}/composite/sobjects", json=payload, headers=headers)

Wrong: Using Composite Batch when you need atomicity

# BAD — Composite Batch has no allOrNone or reference IDs
# If subrequest 2 fails, subrequest 1 is already committed
payload = {"batchRequests": [
    {"method": "POST", "url": "v66.0/sobjects/Account", "richInput": {"Name": "Acme"}},
    {"method": "POST", "url": "v66.0/sobjects/Contact", "richInput": {"LastName": "Doe"}}
]}

Correct: Use Composite API with allOrNone for transactional workflows

# GOOD — allOrNone=true ensures both succeed or both roll back
payload = {
    "allOrNone": True,
    "compositeRequest": [
        {"method": "POST", "url": "/services/data/v66.0/sobjects/Account",
         "referenceId": "refAcct", "body": {"Name": "Acme"}},
        {"method": "POST", "url": "/services/data/v66.0/sobjects/Contact",
         "referenceId": "refCont", "body": {"LastName": "Doe", "AccountId": "@{refAcct.id}"}}
    ]
}

Wrong: Putting >5 queries inside Composite API

# BAD — Composite allows max 5 query/collection subrequests
payload = {"compositeRequest": [
    {"method": "GET", "url": f"/services/data/v66.0/query?q=SELECT...", "referenceId": f"q{i}"}
    for i in range(10)  # 10 queries exceeds the 5-query cap
]}

Correct: Use Composite Batch for independent queries

# GOOD — Composite Batch has no query-count restriction within 25 subrequests
payload = {"batchRequests": [
    {"method": "GET", "url": f"v66.0/query?q=SELECT...{table}"}
    for table in tables[:25]
]}

Common Pitfalls

• Assuming Composite Graph is one transaction: The parent request is NOT transactional — each graph is independently transactional. Graph1 success + graph2 failure = graph1 committed. [src3]
• Ignoring the 5-query cap in Composite API: Only 5 of 25 subrequests can be queries or sObject Collections operations. [src1]
• Not handling partial success in Collections: HTTP 200 even when individual records fail. Check each SaveResult's success field. [src4]
• Conflating Composite and Composite Batch: Batch has no reference IDs, no allOrNone, no transactional behavior. Choose Composite for dependencies, Batch for independent operations. [src1]
• Exceeding governor limits with trigger-heavy objects: 4 Account creates with 3 triggers x 10 SOQL each = 120 queries, exceeding 100-query limit. [src5]
• Using Composite for bulk data loads: Composite is for multi-step workflows, not data loading. For >500 records, use Bulk API 2.0. [src7]

Diagnostic Commands

# Check remaining API limits for this org
curl -H "Authorization: Bearer {token}" \
  https://{instance_url}/services/data/v66.0/limits

# Verify composite resource availability
curl -H "Authorization: Bearer {token}" \
  https://{instance_url}/services/data/v66.0/

# Describe an sObject to check field API names
curl -H "Authorization: Bearer {token}" \
  https://{instance_url}/services/data/v66.0/sobjects/Account/describe

# Test a minimal composite batch request
curl -X POST -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  https://{instance_url}/services/data/v66.0/composite/batch \
  -d '{"batchRequests":[{"method":"GET","url":"v66.0/limits"}]}'

# Check available API versions
curl https://{instance_url}/services/data/

Version History & Compatibility

When to Use / When Not to Use

Important Caveats

• Composite API subrequest limits (25, 500) are hard platform limits — cannot be increased via support tickets or add-on licenses.
• Governor limits are the real bottleneck — trigger-heavy orgs may only be able to use 5-10 subrequests before hitting SOQL or DML limits.
• Sandbox and Developer editions have lower API daily call limits (15K for Developer vs 100K+ for Enterprise).
• The collateSubrequests parameter only affects DML ordering optimization — it does not change allOrNone semantics.
• Composite Graph requires API v50.0+. Integrations pinned to older versions cannot use Composite Graph.
• All composite resources respect field-level security — if the integration user cannot see a field, it is silently omitted from responses.
• Rate limits change with each Salesforce release — always verify against the current Salesforce Developer Limits Quick Reference.