API Success Rate Measurement for Paid Endpoints

API success rate measurement is not a percentage you can publish without a counting rule. For a paid endpoint, the denominator must explain what happened to payment challenges, invalid input, retries, timeouts, upstream failures, and results that never reached the buyer.

A provider can make its success rate look better by excluding inconvenient attempts. It can also make the rate meaningless by including requests that never asked the endpoint to do paid work. The useful metric sits between those errors: every eligible execution attempt is visible, every outcome has a stable class, and the published rate names its window and denominator.

Start with the event being measured

One incoming HTTP request is not always one paid execution. An agent may first receive payment terms, then retry with proof. A network timeout may cause another retry with the same idempotency key. The endpoint may reject malformed input before any billable work begins.

Before calculating a rate, define the event. For endpoint delivery, a practical event is an eligible execution attempt: a request that passed the payment and input gates far enough for the provider to start the promised work. That definition keeps an expected payment challenge out of the endpoint reliability rate while preserving the paid attempt that followed it.

Keep the surrounding states in the records. A payment challenge, invalid proof, schema rejection, execution attempt, retry, and delivered result should not collapse into one generic request count. They answer different operational questions. Payment-aware rate limits need the same separation because a burst of invalid proofs is not the same capacity event as a burst of verified executions.

Publish the numerator and denominator

A rate without counts hides the sample. One delivered result from one attempt and ten thousand delivered results from ten thousand attempts both display as 100 percent. They do not carry the same evidence.

For each measurement window, publish at least:

• Eligible execution attempts in the denominator.
• Delivered results in the numerator.
• Attempts with an HTTP error response.
• Attempts that ended without an HTTP response, including timeouts and connection failures.
• Retries grouped by the original request or idempotency key.
• Exclusions, with a reason for each excluded class.
• The start and end of the observation window.

This is why success rate should travel with measured volume. The denominator lets a buyer judge whether the rate represents sustained traffic or a thin sample. It also makes the arithmetic reproducible. If a marketplace shows only the percentage, a provider cannot verify the observation and a buyer cannot decide how much confidence to place in it.

Classify failure by the promised outcome

HTTP status classes are useful inputs, but they are not the complete policy. A well-formed validation error can be the correct result for malformed input. A response with status 200 can still be an operational failure if the body is truncated, violates the advertised schema, or never reaches the caller.

The classification should follow the endpoint contract. If the paid unit promises one structured profile, success means the execution returned one response that passes the advertised response schema. It does not mean the buyer liked the profile or considered it accurate. Result quality is a different claim and Apiosk does not measure it.

Use stable, low-cardinality failure classes such as timeout, connection failure, provider 5xx, response schema failure, and execution rejected. Preserve the HTTP status when one exists. When no response arrived, record that fact rather than forcing the attempt into a synthetic status code.

Client-caused states need explicit treatment too. A request with missing required input can be excluded from the execution rate if work never began, but the exclusion must be named. A valid request rejected because the provider deployed the wrong schema should not disappear into the same bucket. The rule should reflect who failed to meet the published contract.

Count retries without counting purchases twice

Retries create two valid denominators. The transport denominator counts every attempt because every attempt consumes capacity and can fail. The commercial denominator groups attempts that belong to one logical purchase because the buyer should not appear to have bought the same result several times.

Do not choose one and discard the other. Link them with a stable request identifier or idempotency key. Then you can report that one purchase required three transport attempts, two of which timed out, before one result was delivered. The delivery record stays commercially coherent while the reliability metric still exposes the failed work.

This distinction matters for API monetization without subscriptions. Per-call pricing needs a bounded unit, and the reliability record needs to show whether a retry repeated that unit or completed the original one. Otherwise a provider can overcount revenue events or undercount operational failures.

Compare like with like

Success rates become dangerous when they are placed side by side without matching definitions. One provider may exclude all 4xx responses. Another may include payment challenges. A third may count only requests that returned response headers, which removes connection failures from the denominator entirely.

A neutral comparison needs one observation point and one classification policy across candidates. It should apply the same eligibility gate, timeout boundary, response validation, retry grouping, and measurement window. Only then can measured success rate support comparing paid APIs at decision time.

Even under one policy, the number has limits. Traffic mix differs. An endpoint may have been observed on smaller inputs or at different hours. The result should be described as measured performance for the observed calls, not a guarantee about the next call. Provider terms and result quality remain outside the measurement.

Turn the rate into an operating record

Providers should be able to reconcile the published number with request-level records. Each eligible attempt needs a timestamp, candidate or listing identifier, normalized outcome class, response status when available, duration, logical request identifier, retry count, and whether a result was delivered.

That record supports more than a marketplace score. It shows whether failures cluster around one route, input shape, deployment, or upstream dependency. It also prevents a billing dispute from turning into a search across unrelated gateway and application logs.

The provider does not need to publish request payloads or buyer identifiers. Aggregate counts and a stable classification policy are enough for the public rate. Detailed records can stay within the operational boundary needed for diagnosis and reconciliation.

Where Apiosk fits

Apiosk measures success rate and latency for listings it has proxied enough calls of. In `/v1/compare`, that measured success rate appears beside price, settlement rail, and input compatibility. The 0–100 score is relative to the candidates in that comparison, and the response includes the weights and each candidate's contribution so the buyer can recompute it.

When Apiosk has not measured a dimension for a candidate, it drops that dimension from the weighting and names the omission. It does not assign zero. Apiosk also does not measure result quality or provider terms. External x402 discoveries remain unreviewed and unmeasured, with no candidate identifier, so they cannot enter the comparison chain.

If you run a paid endpoint, list your API with a clear input schema and delivery contract. The useful success rate starts when eligible calls can be observed under one rule, not when a percentage is added to a marketing page.