• State Verified Answer
  • Replies 5 replies
  • Answers 2 answers
  • Subscribers 2 subscribers
  • Views 1 view
  • Users 0 members are here
Options
Related

Batch updates vs single record API calls

Omar Hassan

The current API documentation suggests that all write operations (POST, PATCH, DELETE) must be performed on individual records. However, for large-scale data synchronization scenarios — e.g., updating status on 10,000+ work orders nightly from an external ERP — this presents significant performance concerns.

Specifically, I am seeking clarification on the following:

  1. Does the FieldPulse API expose any batch or bulk endpoints (e.g., /batch, /bulk, or JSON:API-style compound documents) that would allow multiple records to be modified in a single request?
  2. If not, what is the recommended architecture for high-volume operations? I.e., should clients implement exponential backoff with jitter per RFC 7234, or are there higher rate limits available for authenticated integration partners?
  3. Are there any idempotency guarantees (e.g., Idempotency-Key headers per RFC 7230) to prevent duplicate records in the event of network partition during a long-running batch process?

I have reviewed API Rate Limits and Best Practices, but it does not address the batch semantics question directly. Any guidance on the intended pattern here would be appreciated.

  • 0

    Hey Omar — yeah, this is a gap in the docs that we're actively working to address. Short version: no batch endpoints today, but there are some patterns that'll keep you out of trouble.

    Right now every write is single-record. For your 10K nightly sync scenario, I'd recommend:

    // Rough pattern we see working at scale
const BATCH_SIZE = 100;        // concurrent in-flight
const RATE_LIMIT_RPS = 10;     // conservative, burst to 20 if needed
const RETRIES = 3;

// implement token bucket + exponential backoff
// expect ~15-20 min for 10K records with this setup

    The rate limit is per API key, not per account — so you can shard across multiple keys if you really need to move faster, though honestly I'd push back on whether you need all 10K in one batch. Incremental sync (only changed since last run) usually drops that by 90%+.

    Re: idempotency — no Idempotency-Key header yet, but most POSTs return the record ID which you can store and use for PATCH deduplication. For creates specifically, we're looking at adding UUID client generation in Q4; there's an internal ticket you can reference if you need to track it (ENG-4421).

    I'll flag this thread when the batch RFC goes public. It's been discussed but not prioritized — your use case helps make that case.

  • 0

    Workaround we've used: parallelize across multiple API keys as Eli mentioned, but also —

    • ETag on GET: Store last_modified from list endpoint, only sync records where modified_at > checkpoint
    • Connection pooling: Reuse TCP connections, TLS handshake overhead dominates at this volume
    • 429 handling: Backoff header is Retry-After, not exponential by default

    See API Rate Limiting Causing Incomplete Data Exports for a failure mode when this isn't handle'd.

    No bulk endpoint on public roadmap as of 2025-09.

  • 0

    Heads up on something that tripped us: the rate limit is per key, but the 429 response doesn't include reset time in all cases. We've seen empty Retry-After on some endpoints, so YMMV on relying on that header alone.

    Our solution was a simple token bucket with 8 rps sustained, 15 burst, and a local queue with visibility timeout. Works fine for ~5K records/night. For your 10K+ volume, I'd honestly consider asking your CSM about a dedicated integration tier — we've heard they're piloting higher limits for specific partners.

    Worth noting: if you're doing status updates specifically, webhooks + caching layer might let you skip the poll entirely. Depends on whether your ERP can accept the dependency.

  • 0

    Thank you for the detailed responses. A few follow-ups:

    @eli.torres — re: ENG-4421, is there a public issue tracker or changelog entry I can subscribe to for updates on idempotency support? Additionally, regarding sharding across multiple API keys: from a governance perspective, does FieldPulse treat this as acceptable use, or would it be considered a circumvention of rate limit policy (i.e., could result in key revocation)?

    @leo.nakamura — confirmed on the ETag pattern; we are already implementing conditional sync. However, I have observed that the last_modified field on work orders does not update when certain nested resources change (e.g., checklist responses). Is this expected behavior per the resource hierarchy, or should I file a separate issue?

    @devon.marsh — the webhook suggestion is noted, though our ERP requires transactional confirmation before state transition, so async updates introduce complexity we'd prefer to avoid. I will inquire with our CSM regarding integration tier access.

  • 0 in reply to Omar Hassan

    Quick clarifications:

    Multiple keys: Totally acceptable for legitimate architectural reasons (different services, env separation, etc.). What gets you in trouble is spinning up 50 keys just to blast through a limit — we have detection for that pattern. Your use case sounds legit.

    Idempotency tracking: No public tracker yet, unfortunately. I can add you to the early access list for the RFC if you email me directly.

    Nested resource modification: Yeah, that's a known inconsistency. Checklist responses updating work_order.modified_at was supposed to ship in 3.2 but got pulled due to perf concerns on large jobs. It's back in 3.4, currently in beta. Workaround is polling the checklist endpoint separately — not ideal, I know.