Measured Flexport Pagination and Concurrency

Overview

Performance tuning must preserve correctness, account boundaries, and provider stability. Change one pagination, expansion, cache, or concurrency control at a time and validate full reconciliation.

Prerequisites

• Baseline latency, pages, payload size, errors, and business freshness
• Documented pagination model for the selected REST endpoint or MCP tool
• Bounded worker pool and reversible configuration

Instructions

Step 1: Select one bottleneck

Name the operation, surface, dataset window, and business objective. Exclude token acquisition from request concurrency by using a shared cache.

Step 2: Use native pagination

Follow REST response links where documented; for MCP browse_shipments, advance end_cursor while has_next_page is true and keep first within 1–100.

Step 3: Control expansions

Avoid expansion on freight-invoice index calls as recommended; fetch detail only for records that need it.

Step 4: Increase cautiously

Raise one page-size or worker limit for read-only work, measure latency/error/backlog effects, and stop on provider or correctness degradation.

Step 5: Protect mutations

Keep bookings and trade-record writes serialized by business key and outside bulk read tuning.

Step 6: Reconcile the result

Compare counts and terminal cursors/links over the same bounded window, then document the chosen control and rollback.

Authentication

REST calls authenticate with a cached OAuth 2.0 client-credentials Bearer token using audience https://api.flexport.com, or an explicitly accepted broad API key. Use distinct credentials per workload and never log credentials or tokens. MCP calls use the authenticated connection to https://mcp.flexport.com/mcp and remain subject to each tool's documented account permissions.

Tool Discipline

Use Read and Grep for discovery and evidence. Use Write or Edit only for the approved artifact, code, configuration, test, or receipt described by this workflow; do not make an unapproved Flexport-side change.

Output

• Scoped decision or implementation artifact
• Redacted operation and validation receipt
• Failure, rollback, and follow-up ownership record

Return a machine-reviewable receipt in this shape; adapt the operation values, but never place credentials or provider payloads in it:

surface: rest-v3
operation: shipment-read
decision: approved
outcome: verified
evidence:
  release_sha: recorded-out-of-band
  provider_reference: redacted
rollback_owner: logistics-platform

Examples

A shipment-risk scanner tests MCP page sizes of 10 and 50 on the same approved window, verifies identical shipment identities and terminal cursor state, then adopts the faster setting with a bounded worker pool.

Error Handling

Failure	Response
Result counts differ	Reject the tuning change and inspect cursor/link handling.
Latency improves but errors rise	Roll back concurrency and reassess the bottleneck.
Index expansion dominates payload	Remove it and fetch selected details separately.
Mutation entered bulk pool	Drain safely, reconcile outcomes, and restore per-key serialization.

Resources

• First-party source notes
• MCP tools
• Freight invoices tutorial
• Shipment API tutorial