Anvil › Docs › /v1/input-lag

Input lag API: milliseconds from button press to picture, and what would help most

Input lag is six small waits added together: the controller's next report, the trip over the cable or radio, the game noticing, the game drawing the frame, the screen's next refresh and the screen's own processing. A console on a TV with its picture extras on lands around 130 ms; the same setup with game mode and a cable is nearer 70 ms. This endpoint adds the pieces up for a setup and ranks the changes that would save the most.

Parameters

Example

Request:

GET https://api.oddlathe.com/v1/input-lag?link=bt&rate=250&fps=60&hz=60&screen=tv

Response (generated by the real code when these docs were last built; random or time-based values will differ for you):

{
 "mode": "estimate",
 "setup": {
  "rate_hz": 250,
  "link": "bt",
  "link_name": "Bluetooth",
  "fps": 60,
  "effective_fps": 60,
  "pipe": "normal",
  "pipe_name": "Normal",
  "hz": 60,
  "screen": "tv",
  "screen_name": "TV with picture extras on (game mode off)",
  "screen_ms": 70
 },
 "typical_ms": 131,
 "best_ms": 110.3,
 "worst_ms": 151.7,
 "wobble_ms": 41.3,
 "frames_at_60": 7.9,
 "parts": [
  {
   "key": "poll",
   "name": "Waiting for the next report (polling)",
   "ms": 2
  },
  {
   "key": "link",
   "name": "The trip (cable or wireless)",
   "ms": 9
  },
  {
   "key": "wait",
   "name": "Waiting for the game to look",
   "ms": 8.3
  },
 …

Code examples

curl 'https://api.oddlathe.com/v1/input-lag?link=bt&rate=250&fps=60&hz=60&screen=tv'

const params = new URLSearchParams({
  link: "bt",
  rate: "250",
  fps: "60",
  hz: "60",
  screen: "tv"
});
const res = await fetch(`https://api.oddlathe.com/v1/input-lag?${params}`);
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();
console.log(data);

import json, urllib.parse, urllib.request

params = urllib.parse.urlencode({"link": "bt", "rate": "250", "fps": "60", "hz": "60", "screen": "tv"})
url = "https://api.oddlathe.com/v1/input-lag?" + params
# Send a User-Agent: the edge network refuses Python's default one.
req = urllib.request.Request(url, headers={"User-Agent": "my-script/1.0"})
with urllib.request.urlopen(req, timeout=10) as r:
    data = json.load(r)
print(data)

When it's useful

• Setup helpers and buying guides: show what a TV's game mode or a 1000 Hz controller really saves
• Game launchers or companion apps that suggest the one setting worth changing
• Comparing two setups side by side with <code>mode=compare</code>
• Teaching why the screen, not the controller, is usually the big piece

Good to know

• mode=estimate (default) takes link, rate, fps, pipe, hz and screen (or screen_ms from a review), or starts from example=sofa|sofafix|pc|laptop and overrides from there. Returns typical_ms, best_ms, worst_ms, frames_at_60, the six parts, the biggest part, a verdict (Excellent under 30 ms up to Sluggish at 120+) and ranked suggestions.
• mode=compare reads setup B from the same names prefixed b_ (for example b_example=sofafix or b_screen=gametv) and returns both plus difference_ms.
• mode=options lists every choice with its figures. Words like cable, bluetooth, reflex and gamemode are accepted as aliases; anything else that isn't on the list is a 400, never silently swapped.
• Figures are rounded typical values, not a measurement of your hardware. V-Sync caps the game at the refresh rate and queues about a frame more.
• Browser UI: Tooltern input lag calculator with the same model, a coloured breakdown bar and pin-to-compare (nothing leaves your device). Playful version: how a controller talks to a console.

How long it takes from pressing a button to seeing it on screen, using rounded typical figures: waiting for the next polling report, the trip over a cable or wireless, waiting for the game to read input, the game making the picture (1.5 to 3 frames), waiting for the screen's refresh and the screen's own processing. Returns typical, luckiest and unluckiest totals, frames late at 60 fps, a five-band verdict and the best single change per setting ranked by milliseconds saved. mode=compare puts two setups side by side (B uses b_ parameters) and mode=options lists every choice. Same model as the Tooltern input lag calculator. Pure maths; nothing is stored.

Errors

Errors are JSON like {"error": {"code": "…", "message": "…"}}. The ones this endpoint can return:

• bad_param (400): a value is the wrong type or out of range (the message says which)
• rate_limited (429): over 60 requests a minute; wait for Retry-After seconds

Questions

Related endpoints

• /v1/video-sizeVideo file size: MB for a length, what fits in free space, bitrate and ffmpeg commands for a target size
• /v1/stream-dataStreaming data use: GB per hour, monthly allowance planner, film size, hours from GB
• /v1/broadband-needBroadband speed needed: busiest-moment Mb/s down and up, plan tier, does your plan cope, download times
• /v1/unitsConvert length, mass, temperature, data-size or data-rate units

Prefer a page to an API?

• Input lag calculator (six-part breakdown, biggest fixes) on Tooltern: same job, nothing leaves your browser.

Published 7 November 2026 · OpenAPI 3.1 spec · Limits and privacy