An active shipment slot and a monthly lookup are different resources. Being able to store or monitor a record does not mean you have enough successful lookups to refresh it throughout the month. Plan both limits together before importing a large order backlog.
Trace monitoring is best effort for up to 30 days, with roughly six-hour targets after a verified check and failure backoff. These are operating targets, not a guarantee that every shipment will receive four fresh observations every day.
Estimate the lookup budget before enabling a cohort
Start with the number of parcels, the period you expect them to remain active and the successful refreshes you want to budget per day. Add successful direct API calls, cached responses, async job items and any explicitly requested stale fallbacks. They share the account’s lookup allowance.
Planning example · not a refresh guarantee
10 parcels × 5 days × 4 successful refreshes/day = 200 lookups
That would consume the entire standard Free monthly allowance.
Customer-triggered successful checks would need additional budget.
Actual refreshes depend on source availability, scheduling and closure.Distinguish active capacity from usage allowance
The standard public plans have separate active-record limits and monthly successful-lookup quotas. The active cap controls how many records can be monitored concurrently; it does not multiply the monthly allowance. All plans also have a total stored-record cap.
| Plan | Active shipment cap | Monthly successful lookups |
|---|---|---|
| Free | 100 | 200 |
| Startup | 1,000 | 5,000 |
| Business | 5,000 | 25,000 |
| Scale | 20,000 | 100,000 |
Explain why a refresh has not happened
Inspect last_checked_at, last_error, next_refresh_at and monitor_until. A quota-postponed refresh is not a carrier failure, and a record awaiting its first observation has not yet established a verified shipment state. Failed refreshes release reservations and back off rather than consuming monthly lookup quota.
Monitoring closes after delivery or expiry. Stop a record deliberately when your application no longer needs refreshes. A closed record needs a new cycle to resume; do not imply that editing its tracking identity will reopen the old journey.
Use the account’s real reset boundary
Free and manually assigned non-Stripe accounts use UTC calendar months. Paid quota periods follow confirmed Stripe subscription dates. Read the account’s reset information instead of scheduling every customer for a local midnight reset.
An existing Free account may temporarily retain its previous allowance until the transition date shown in Billing. New Free accounts use 200. Account-specific transition information should not be advertised as a permanent public free tier.
Common questions
Does a failed monitoring refresh consume a lookup?
No. Successful refreshes consume quota; failed refreshes release their reservation. A failure still affects freshness and can cause backoff.
References & next steps
Implementation details were checked against Trace’s current API. External product details may change; verify the linked documentation before deciding.