Track a USPS package and read its scan history

Follow a USPS shipment from its public tracking result. Collect the current summary and the expanded history together, so a caller can distinguish a delivery estimate from a completed delivery and a purchased label from an accepted shipment. Return what USPS displays, retaining missing fields and ambiguous outcomes instead of filling them from assumptions.

Use Cases

• Answer where a shipment was last scanned and what USPS currently says about its progress.
• Retrieve a delivery estimate alongside the events supporting the current status.
• Identify a delivery attempt, pickup instruction, or other exception that needs the caller's attention.
• Check several supplied identifiers independently without combining their shipment histories.

Automation Flow

1. Prepare one lookup. Keep the requested identifier as a string and remove formatting whitespace without dropping leading zeroes. Do not reject it solely because it exceeds a presumed domestic length. If the input appears to contain several identifiers, separate the lookups before navigation; never choose a candidate result on the caller's behalf.

2. Open the public result in a browser. Start with https://tools.usps.com/go/TrackConfirmAction?qtc_tLabels1={encoded-tracking-id}, URL-encoding the cleaned identifier. If USPS redirects to /tracking/{tracking-id}, follow that navigation. If it returns an empty entry form, use the visible tracking input and submit once. The homepage's #home-input is an alternative starting point; when duplicate submit controls interfere, submit the visible input's own form.

3. Check access and rendering before interpreting the shipment. Inspect both the page title and the result region. An access-denied screen, challenge, or blank document is a retrieval failure, not a package status. Wait for the result region to settle rather than relying only on the navigation load event. If the session remains blocked, report that limitation; a different browser or permitted proxy configuration is a troubleshooting option, not a guaranteed prerequisite or cure.

4. Bind the result to the request. Read the identifier displayed with the shipment, normalize its whitespace, and compare it with the requested value. The URL alone is insufficient proof of identity. If the displayed number differs, stop and retry a fresh lookup. If several shipments are offered, return their candidate identifiers for selection. If a populated result has no readable identifier, report that identity could not be verified rather than attaching its events to the request.

5. Capture the current summary. Locate the status within the matching result region, not a general page heading or help article. The .tracking-progress-bar-status-container anchor from the source notes is a candidate to inspect, not a required selector: use the current DOM and accessible labels if that structure has changed. Record the exact status text and explanatory text before assigning a broad category:

   Evidence in the shipment result	Category and interpretation
   A completed delivery statement	delivered; preserve the actual delivery time separately from any estimate.
   An explicit out-for-delivery statement	out_for_delivery; do not count it as delivered.
   Acceptance, possession, facility movement, or transit information	in_transit; possession of the item must not be classified as label creation.
   A label or pre-shipment statement explicitly saying USPS is awaiting the item	awaiting_item; do not infer a physical scan.
   A failed attempt, notice, or availability-for-pickup statement	delivery_action; preserve the instruction without initiating an action.
   A delay or routing/address problem that does not fit the categories above	exception; include USPS's wording so the category does not conceal the cause.
   An unavailable-status message without a usable shipment summary	unavailable; retain the explanation without asserting the number is invalid or that USPS has never received the item.
   An explicit statement that the lookup could not locate the requested information	not_found; describe this lookup outcome, not the package's existence.
   A readable status whose meaning is unclear	unknown; return its exact wording for interpretation.

   A populated result must not fall through to “not loaded” simply because its heading differs from an unavailable-result heading.

6. Read locations and delivery timing as separate fields. Capture the location associated with the latest scan, using city, state, and postal code when available. Keep a facility label separately if USPS supplies one; do not turn it into an inferred street address. For an estimate, retain the displayed date and time window verbatim. For completed delivery, retain the actual delivery text instead. Do not invent an ISO timestamp or timezone from a date-only label, and do not treat an old estimate as proof of delivery.

7. Expand the event history. Find the visible history control and open it only if collapsed. Read every loaded event row within this shipment, including its status, date/time text, and location. If a “more” control loads additional events, continue until no additional rows appear or retrieval fails. Preserve the displayed order and state which order it is; reverse or sort only when the timestamps establish chronology. Keep distinct scans even when they share a status label. Open Product Information separately when needed to read the service name.

8. Return the shipment with an extraction report. Include these fields, keeping unavailable values null:

   • trackingId, displayedTrackingId, and identityVerified.
   • statusCategory, statusText, and message.
   • currentLocation, expectedDeliveryText, deliveredAtText, and serviceType.
   • events, with each row's statusText, timestampText, and locationText.
   • historyState: loaded, partial, unavailable, or not_extracted; also include eventOrder, sourceUrl, and retrievedAt.

   Use events: null when the history was not extracted or could not be opened. Use an empty array only when the inspected result actually presents no events. If some rows were collected before an interruption, keep them with historyState: partial. “Loaded” describes the available page content, not a guarantee that USPS exposes every scan it holds internally.

9. Finish without changing delivery preferences. Leave notification enrollment, delivery instructions, holds, and redelivery untouched. Close or release a session created solely for this lookup. When sharing debug output, mask tracking identifiers in URLs, page captures, and logs, and omit street-level delivery details.

Params

Possible Friction Points

Before moving this draft into the published catalog, validate a real populated lookup end to end: matching identifier, current summary, location/timing fields when present, and expanded scan rows. Also exercise an unavailable result and an access or loading failure. Record which states were actually observed; fabricated fixtures and source notes can check logic but cannot establish live coverage.