What should a progress percentage mean for a job that discovers more work as it runs?

A progress percentage for a job that discovers more work should mean progress against the work currently known or credibly estimated, not a fake promise about the final total. If the denominator can grow, do not freeze it up front. Report phase, completed units, and whether the total is known. Show a percentage only when it is honest; otherwise mark the operation indeterminate and keep updates monotonic and useful. That aligns with accessible progress semantics in MDN’s progressbar role reference and with long-running operation metadata guidance in Google AIP-151.

What should the percentage actually represent?

Use this contract:

• phase: what kind of work is happening now.
• completed: durable units finished.
• known_total: total units currently discovered.
• estimated_total: optional forecast of final units.
• percent: only derived from known_total or estimated_total, with the basis named.
• indeterminate: true when no honest denominator exists.

The key rule is that completed must never go backwards. known_total may increase as the system discovers more work. That means a percentage based on known work can stall or even dip if you recompute it naively. Avoid that UI surprise by tying percentages to phases, not pretending the whole job was measurable from the start.

For APIs, put these fields in operation metadata. Google AIP-151 explicitly says metadata is for information such as progress and partial failures on each operation poll.

How should a fan-out job report progress across phases?

Split the job into explicit phases with separate semantics.

Example: import a folder, parse manifests, then process each discovered file.

1. Discovery phase

   • Status: Discovering files
   • Percentage: indeterminate
   • Counters: directories_scanned=120, files_discovered=3,240

2. Processing phase

   • Status: Processing files
   • Percentage: determinate against discovered work
   • Counters: files_processed=810, known_total=3,240, percent=25

3. Late fan-out phase if processing a file can enqueue more files

   • Keep completed monotonic.
   • If new files are found, increase known_total and say so in status text: Processing files; discovered 140 additional files.
   • If that changing denominator would confuse users, switch the percentage label to 25% of discovered work processed rather than 25% complete.

For UI and accessibility, this distinction matters. MDN’s progressbar role reference says aria-valuenow should be omitted when the value is indeterminate, and recommends aria-valuetext when a plain percentage would be misleading.

When should you show an estimate instead of exact progress?

Show an estimate only if you can explain its basis and keep it stable enough to help. Good examples are batched imports where historical averages make final file count predictable, or tree walks where the frontier size gives a reasonable forecast.

A solid pattern is:

• percent_known = completed / known_total
• percent_estimated = completed / estimated_total
• expose one of them, labeled clearly

If you choose an estimate, never present it as exact completion. Call it estimated progress and keep the raw counters visible for engineers and operators.

What are the limits of this contract?

This approach fits long-running jobs with meaningful units of work: files, records, partitions, child tasks. It is less useful for jobs dominated by a few highly variable steps, such as one huge database rewrite followed by a tiny cleanup phase. In those cases, phase status and milestone events are more truthful than a percentage.

Also, define the ordering boundary carefully: only count a unit as complete after the system has durably recorded the result for that unit. Do not increment completed on a preflight check or before the write that makes the result observable.

Follow-up: What if users insist on a single percentage?

Give one, but name it honestly: estimated overall progress or progress on discovered work. Pair it with phase text so the number is not carrying all meaning.

Follow-up: Should percent ever go backwards?

Prefer no. Keep the displayed percent monotonic by phase, or switch to indeterminate during denominator growth. Raw counters may change; the top-line indicator should stay understandable.

Next step: define your operation metadata schema first, then decide which phases are determinate, which are indeterminate, and what exact event makes a work unit count as completed.

Reviewed: 2026-09-05