https://kvasyr.com/_next/static/chunks/pages/docs/backfills-0f7abc85ce0dd0fc.js

1(self.webpackChunk_N_E=self.webpackChunk_N_E||[]).push([[827],{2826:function(e,i,n){(window.__NEXT_P=window.__NEXT_P||[]).push(["/docs/backfills",function(){return n(4073)}])},4073:function(e,i,n){"use strict";n.r(i),n.d(i,{useTOC:function(){return o}});var s=n(5893),t=n(7812),r=n(3551),a=n(8925),l=n(5192);function o(e){return[{value:"Who Can Use Backfills",id:"who-can-use-backfills",depth:2},{value:"How To Request A Backfill",id:"how-to-request-a-backfill",depth:2},{value:"Dashboard",id:"dashboard",depth:3},{value:"API",id:"api",depth:3},{value:"When It Runs",id:"when-it-runs",depth:2},{value:"Throughput Guardrails",id:"throughput-guardrails",depth:2},{value:"Statuses You Will See",id:"statuses-you-will-see",depth:2},{value:"Credits And Delivery Behavior",id:"credits-and-delivery-behavior",depth:2},{value:"Tips For Better Results",id:"tips-for-better-results",depth:2},{value:"Related",id:"related",depth:2}]}i.default=(0,t.c)(function(e){let{toc:i=o(e)}=e,n={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",li:"li",p:"p",pre:"pre",span:"span",strong:"strong",ul:"ul",...(0,a.a)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(n.h1,{children:"Backfills"}),"\n",(0,s.jsx)(n.p,{children:"Backfills let you replay historical blocks for one subscription so you can\ncapture older matching events."}),"\n",(0,s.jsx)(n.p,{children:"Use this when you created a subscription late, had your endpoint offline, or\nneed a historical range for analysis."}),"\n",(0,s.jsx)(n.h2,{id:i[0].id,children:i[0].value}),"\n",(0,s.jsx)(n.p,{children:"Backfill is available when:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"your plan includes backfill,"}),"\n",(0,s.jsxs)(n.li,{children:["your subscription has ",(0,s.jsx)(n.strong,{children:"Stored Events"})," enabled."]}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"If backfill is unavailable, check your plan/subscription settings in\nDashboard."}),"\n",(0,s.jsx)(n.h2,{id:i[1].id,children:i[1].value}),"\n",(0,s.jsx)(n.h3,{id:i[2].id,children:i[2].value}),"\n",(0,s.jsxs)(n.p,{children:["Open ",(0,s.jsx)(n.strong,{children:"Dashboard -> Subscriptions -> [subscription] -> Backfill"})," and enter:"]}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"from_block"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.code,{children:"to_block"})}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"You can provide one side only to request a single block."}),"\n",(0,s.jsx)(n.p,{children:"After queueing, Kvasyr shows:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"request ID"}),"\n",(0,s.jsx)(n.li,{children:"estimated run window start time"}),"\n",(0,s.jsx)(n.li,{children:"request history with status and cursor progress"}),"\n"]}),"\n",(0,s.jsx)(n.h3,{id:i[3].id,children:i[3].value}),"\n",(0,s.jsx)(n.pre,{icon:l.Fx,tabIndex:"0","data-language":"bash","data-word-wrap":"","data-copy":"",children:(0,s.jsxs)(n.code,{children:[(0,s.jsxs)(n.span,{children:[(0,s.jsx)(n.span,{style:{"--shiki-light":"#6F42C1","--shiki-dark":"#B392F0"},children:"curl"}),(0,s.jsx)(n.span,{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"},children:" -sS"}),(0,s.jsx)(n.span,{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"},children:" https://app.kvasyr.com/v1/backfill"}),(0,s.jsx)(n.span,{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"},children:" \\"})]}),"\n",(0,s.jsxs)(n.span,{children:[(0,s.jsx)(n.span,{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"},children:"  -H"}),(0,s.jsx)(n.span,{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"},children:' "Authorization: Bearer ${'}),(0,s.jsx)(n.span,{style:{"--shiki-light":"#24292E","--shiki-dark":"#E1E4E8"},children:"KVASYR_API_KEY"}),(0,s.jsx)(n.span,{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"},children:'}"'}),(0,s.jsx)(n.span,{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"},children:" \\"})]}),"\n",(0,s.jsxs)(n.span,{children:[(0,s.jsx)(n.span,{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"},children:"  -H"}),(0,s.jsx)(n.span,{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"},children:' "Content-Type: application/json"'}),(0,s.jsx)(n.span,{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"},children:" \\"})]}),"\n",(0,s.jsxs)(n.span,{children:[(0,s.jsx)(n.span,{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"},children:"  -H"}),(0,s.jsx)(n.span,{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"},children:' "Idempotency-Key: backfill-sub123-500-1500"'}),(0,s.jsx)(n.span,{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"},children:" \\"})]}),"\n",(0,s.jsxs)(n.span,{children:[(0,s.jsx)(n.span,{style:{"--shiki-light":"#005CC5","--shiki-dark":"#79B8FF"},children:"  -d"}),(0,s.jsx)(n.span,{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"},children:" '{"})]}),"\n",(0,s.jsx)(n.span,{children:(0,s.jsx)(n.span,{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"},children:'    "subscription_id": 123,'})}),"\n",(0,s.jsx)(n.span,{children:(0,s.jsx)(n.span,{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"},children:'    "from_block": 500,'})}),"\n",(0,s.jsx)(n.span,{children:(0,s.jsx)(n.span,{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"},children:'    "to_block": 1500'})}),"\n",(0,s.jsx)(n.span,{children:(0,s.jsx)(n.span,{style:{"--shiki-light":"#032F62","--shiki-dark":"#9ECBFF"},children:"  }'"})})]})}),"\n",(0,s.jsxs)(n.p,{children:["Use ",(0,s.jsx)(n.code,{children:"Idempotency-Key"})," so retries do not create duplicate requests."]}),"\n",(0,s.jsx)(n.h2,{id:i[4].id,children:i[4].value}),"\n",(0,s.jsx)(n.p,{children:"Backfills run in scheduled windows (not instantly at request time)."}),"\n",(0,s.jsx)(n.p,{children:"What this means for you:"}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["your request enters a queue first (",(0,s.jsx)(n.code,{children:"queued"}),"),"]}),"\n",(0,s.jsx)(n.li,{children:"Kvasyr batches compatible requests to reduce RPC load,"}),"\n",(0,s.jsx)(n.li,{children:"each window has an internal RPC compute budget, so long catch-up runs are\nintentionally throttled,"}),"\n",(0,s.jsx)(n.li,{children:"the estimate in panel is best-effort and can move if queue load changes."}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:i[5].id,children:i[5].value}),"\n",(0,s.jsx)(n.p,{children:"Kvasyr applies a per-window estimated RPC budget for backfill work. This keeps\nhistorical catch-up from hammering providers during bursts."}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:["default: ",(0,s.jsx)(n.code,{children:"BACKFILL_MAX_ESTIMATED_CU_PER_TICK=12000"})]}),"\n",(0,s.jsxs)(n.li,{children:["estimate model:","\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"eth_getLogs"})," ~= 60 CU"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"eth_getBlockByNumber"})," ~= 20 CU"]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"eth_blockNumber"})," ~= 10 CU"]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(n.p,{children:"If a window hits its budget, remaining work is deferred to the next window\ninstead of continuing unbounded."}),"\n",(0,s.jsx)(n.h2,{id:i[6].id,children:i[6].value}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"queued"}),": waiting for an execution window."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"processing"}),": currently scanning your requested range."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"paused_credits"}),": stopped because credits ran out; resumes after credits are available."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"completed"}),": done."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"completed_noop"}),": nothing eligible to scan for that request."]}),"\n",(0,s.jsxs)(n.li,{children:[(0,s.jsx)(n.code,{children:"failed"}),": request did not finish and needs review/retry."]}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:i[7].id,children:i[7].value}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Backfill matches consume credits the same way as live indexing."}),"\n",(0,s.jsx)(n.li,{children:"Existing matches are deduplicated, so already-matched subscription events are\nnot re-fired as new matches."}),"\n",(0,s.jsx)(n.li,{children:"Depending on workspace configuration, matched backfill events can also enqueue\nwebhook deliveries in addition to stored-event matching."}),"\n",(0,s.jsxs)(n.li,{children:["For plan-change/reset timing details, see\n",(0,s.jsx)(n.a,{href:"/docs/account-and-credits",children:"Managing Account and Credits"}),"."]}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:i[8].id,children:i[8].value}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:"Prefer focused ranges over very deep scans when possible."}),"\n",(0,s.jsx)(n.li,{children:"Split very large history requests into smaller chunks if you need faster\ncheckpoints."}),"\n",(0,s.jsx)(n.li,{children:"Monitor cursor/status in subscription detail to confirm forward progress."}),"\n"]}),"\n",(0,s.jsx)(n.h2,{id:i[9].id,children:i[9].value}),"\n",(0,s.jsxs)(n.ul,{children:["\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.a,{href:"/docs/panel-subscriptions",children:"Panel Subscriptions"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.a,{href:"/docs/api-keys-and-api",children:"API Keys and API"})}),"\n",(0,s.jsx)(n.li,{children:(0,s.jsx)(n.a,{href:"/docs/outages-and-recovery",children:"Outages and Recovery"})}),"\n"]})]})},"/docs/backfills",{filePath:"pages/docs/backfills.mdx",timestamp:1782417729e3,pageMap:r.v,frontMatter:{title:"Backfills",description:"How backfills work for regular Kvasyr users, including queueing, timing, statuses, and credits."},title:"Backfills"},"undefined"==typeof RemoteContent?o:RemoteContent.useTOC)},3551:function(e,i,n){"use strict";n.d(i,{v:function(){return s}});let s=[{data:{index:{title:"Home",type:"page",theme:{breadcrumb:!1,sidebar:!1,toc:!1,pagination:!1}},dashboard:{title:"Dashboard",type:"page",href:"https://app.kvasyr.com",newWindow:!0},docs:{title:"Docs",type:"page"},search:{title:"Search",type:"page",theme:{breadcrumb:!1,sidebar:!1,toc:!1,pagination:!1}}}},{name:"docs",route:"/docs",children:[{data:{index:"Overview","getting-started":"Getting Started","api-keys-and-api":"API Keys and API",backfills:"Backfills","account-and-credits":"Managing Account and Credits","kvasyr-api-skill":"LLM Skill: Kvasyr API",chains:"Chains",configuration:"Configuration","cost-tuning":"Cost Tuning","panel-subscriptions":"Panel: Subscriptions","panel-webhooks":"Panel: Webhooks","panel-notifications":"Panel: Notifications","outages-and-recovery":"Outages and Recovery",legal:"Legal, Privacy, and Refunds","self-hosting":"Self-hosting","change-log":"Changelog"}},{name:"account-and-credits",route:"/docs/account-and-credits",frontMatter:{title:"Managing Account and Credits",description:"How plan changes, credit charging, and reset timing work in Kvasyr Cloud."}},{name:"api-keys-and-api",route:"/docs/api-keys-and-api",frontMatter:{title:"API Keys and API",description:"What API keys are for in Kvasyr Cloud and how SaaS users automate subscriptions."}},{name:"backfills",route:"/docs/backfills",frontMatter:{title:"Backfills",description:"How backfills work for regular Kvasyr users, including queueing, timing, statuses, and credits."}},{name:"chains",route:"/docs/chains",frontMatter:{title:"Chains",description:"Supported chains and finality behavior."}},{name:"change-log",route:"/docs/change-log",frontMatter:{title:"Changelog",description:"Release notes for Kvasyr Cloud."}},{name:"configuration",route:"/docs/configuration",frontMatter:{title:"Configuration",description:"Configure Kvasyr Cloud subscriptions, delivery behavior, and account-level controls."}},{name:"cost-tuning",route:"/docs/cost-tuning",frontMatter:{title:"Cost Tuning",description:"Tune indexer and webhook behavior for RPC/CU efficie

1ncy."}},{name:"getting-started",route:"/docs/getting-started",frontMatter:{title:"Getting Started",description:"Launch Kvasyr Cloud quickly and receive your first webhook."}},{name:"index",route:"/docs",frontMatter:{title:"Overview",description:"Kvasyr Cloud docs for product teams integrating EVM event webhooks."}},{name:"kvasyr-api-skill",route:"/docs/kvasyr-api-skill",frontMatter:{title:"LLM Skill: Kvasyr API",description:"Install and use the repository skill that lets LLMs create and manage Kvasyr API workflows."}},{name:"legal",route:"/docs/legal",frontMatter:{title:"Legal, Privacy, and Refunds",description:"Practical Kvasyr Cloud terms, privacy summary, and billing/refund policy."}},{name:"outages-and-recovery",route:"/docs/outages-and-recovery",frontMatter:{title:"Outages and Recovery",description:"How Kvasyr catches up after downtime and how webhook retry behavior affects clients."}},{name:"panel-notifications",route:"/docs/panel-notifications",frontMatter:{title:"Panel Notifications",description:"Configure notification events, channels, Telegram credentials, and test delivery."}},{name:"panel-subscriptions",route:"/docs/panel-subscriptions",frontMatter:{title:"Panel Subscriptions",description:"How to use every control in the panel subscription forms."}},{name:"panel-webhooks",route:"/docs/panel-webhooks",frontMatter:{title:"Panel Webhooks",description:"Webhook setup, verification, test deliveries, and secrets."}},{name:"self-hosting",route:"/docs/self-hosting",children:[{data:{index:"Overview",api:"API",monitoring:"Monitoring",metrics:"Metrics","panel-admin-users":"Panel: Admin Users","panel-system-status":"Panel: System Status"}},{name:"api",route:"/docs/self-hosting/api",frontMatter:{title:"API",description:"API reference entry point for self-hosted and white-label automation flows."}},{name:"index",route:"/docs/self-hosting",frontMatter:{title:"Self-hosting",description:"Operator guidance for self-hosted and white-label Kvasyr deployments."}},{name:"metrics",route:"/docs/self-hosting/metrics",frontMatter:{title:"Metrics",description:"What Kvasyr exports on /metrics and how to use it in self-hosted operations."}},{name:"monitoring",route:"/docs/self-hosting/monitoring",frontMatter:{title:"Monitoring",description:"Prometheus and Grafana setup for full Kvasyr observability."}},{name:"panel-admin-users",route:"/docs/self-hosting/panel-admin-users",frontMatter:{title:"Panel Admin Users",description:"Admin workflows for user plan and credit management."}},{name:"panel-system-status",route:"/docs/self-hosting/panel-system-status",frontMatter:{title:"Panel System Status",description:"Admin-only instance health snapshot shown in panel."}}]}]},{name:"index",route:"/",frontMatter:{title:"Kvasyr - Managed EVM Webhook SaaS",description:"Managed EVM event delivery with signed webhooks, team workflows, and usage-based plans.",timestamp:!1}},{name:"search",route:"/search",frontMatter:{title:"Search",description:"Full-text search for the Kvasyr docs."}}]}},function(e){e.O(0,[812,888,774,179],function(){return e(e.s=2826)}),_N_E=e.O()}]);