`sl.subgraphs`

Deploy a subgraph, read its rows and watch its operations. The same data the Subgraphs API serves over HTTP.

@secondlayer/sdk@15.5.019 methodsfrom source with openpkgSubgraphs guide Subgraphs API

list()	{ data: SubgraphSummary[] }	List the subgraphs deployed to this instance.
status(name)	SubgraphDetail	Get a subgraph's health, sync position, and tables.
openapi(name, options)	Record<string, unknown>	Get a subgraph's OpenAPI spec.
schema(name, options)	SubgraphAgentSchema	Get a subgraph's schema as JSON, shaped for agents.
markdown(name, options)	string	Get a subgraph's generated API docs as Markdown text.
reindex(name)	ReindexResponse	Rebuild a subgraph from scratch.
stop(name)	{ message: string; operationId?: st…	Stop a running reindex or backfill.
backfill(name, options)	ReindexResponse	Process one block range.
gaps(name, opts)	SubgraphGapsResponse	List the block ranges a subgraph is missing.
delete(name, options)	{ message: string }	Delete a subgraph and its tables.
rows(name, table, params)	SubgraphRowsEnvelope<T>	Read a table's rows, one cursor page at a time.
operations(name)	{ operations: SubgraphOperationStat…	Recent reindex/backfill operations for a subgraph, newest first.
getOperation(name, operationId)	SubgraphOperationStatus	Get the status of one reindex, backfill, or stop operation.
deploy(data)	DeploySubgraphResponse	Create or update a subgraph.
getSource(name)	SubgraphSource	Get a deployed subgraph's source.
bundle(data)	BundleSubgraphResponse	Bundle a TypeScript subgraph source on the server.
count(name, table, params)	{ count: number }	Count the rows in a table that match a filter.
aggregate(name, table, params)	SubgraphAggregateResponse	Compute scalar aggregates over a table's matching rows.
typed(def)	InferSubgraphClient<T>	Returns a typed client for a subgraph defined with `defineSubgraph()`.

sl.subgraphs.list()

REST GET /api/subgraphs source

List the subgraphs deployed to this instance.

Each summary has the status, the last processed block against the chain tip, progress, gapCount, and an integrity flag.

sl.subgraphs.list(): Promise<{ data: SubgraphSummary[] }>

sl.subgraphs.status(name)

REST GET /api/subgraphs/{name}source

Get a subgraph's health, sync position, and tables.

The verify step after a deploy, reindex, or backfill: poll it until sync catches the tip.

sl.subgraphs.status(name: string): Promise<SubgraphDetail>

Parameters

hover a row to find it in the code

Required

namerequiredstring

Returns Promise<SubgraphDetail>

name: string
version: string
schemaHash: string
pin: sha256 over schema, handler bundle, startBlock, network and runtime. Null for subgraphs deployed before pins existed.
verification: Null for subgraphs deployed before levels were derived.
status: string
lastProcessedBlock: number
description: string
sources: Record<string, unknown>
definition: Record<string, unknown>
health: { totalProcessed: number; totalErrors: number; errorRate: number; lastError: st…
sync: SubgraphSyncInfo
tables: Record<string, { endpoint: string; columns: Record<string, { type: string; null…
createdAt: string
updatedAt: string

sl.subgraphs.openapi(name, options)

REST GET /api/subgraphs/{name}/openapi.jsonsource

Get a subgraph's OpenAPI spec.

Describes the REST routes generated for each table. Pass serverUrl to set the server the spec advertises.

sl.subgraphs.openapi(

options?: SubgraphSpecOptions,

): Promise<Record<string, unknown>>

Parameters

hover a row to find it in the code

Required

namerequiredstring

Options

`options.serverUrl`string
`options.generatedAt`string

sl.subgraphs.schema(name, options)

REST GET /api/subgraphs/{name}/schema.jsonsource

Get a subgraph's schema as JSON, shaped for agents.

Per table: the endpoints, columns, indexes, which fields are sortable, selectable, searchable, or filterable, and a ready example query. Pass serverUrl to set the server the endpoints use.

sl.subgraphs.schema(

options?: SubgraphSpecOptions,

): Promise<SubgraphAgentSchema>

Parameters

hover a row to find it in the code

Required

namerequiredstring

Options

`options.serverUrl`string
`options.generatedAt`string

Returns Promise<SubgraphAgentSchema>

name: string
version: string
description: string
schemaHash: string
pin: string
generatedAt: string
serverUrl: string
sources: Record<string, unknown>
tables: Record<string, { endpoint: string; countEndpoint: string; aggregateEndpoint?: s…

sl.subgraphs.markdown(name, options)

REST GET /api/subgraphs/{name}/docs.mdsource

Get a subgraph's generated API docs as Markdown text.

Pass serverUrl to set the server the examples use.

sl.subgraphs.markdown(name: string, options?: SubgraphSpecOptions): Promise<string>

Parameters

hover a row to find it in the code

Required

namerequiredstring

Options

`options.serverUrl`string
`options.generatedAt`string

sl.subgraphs.reindex(name)

REST POST /api/subgraphs/{name}/reindex source

Rebuild a subgraph from scratch.

A reindex always drops and rebuilds the whole subgraph, so it takes no block range; the API rejects one with REINDEX_RANGE_NOT_SUPPORTED. Use backfill to process a specific range. While a reindex or backfill is already running the API answers 409 with code OPERATION_IN_PROGRESS; poll operations until it finishes.

sl.subgraphs.reindex(name: string): Promise<ReindexResponse>

Parameters

hover a row to find it in the code

Required

namerequiredstring

Returns Promise<ReindexResponse>

message: string
fromBlock: number
toBlock: string | number
operationId: string
status: "queued" | "running" | "cancel_requested"

sl.subgraphs.stop(name)

REST POST /api/subgraphs/{name}/stop source

Stop a running reindex or backfill.

Requests the cancel and resolves with the operationId and a cancel_requested status. Poll getOperation until status is terminal. Throws a 404 with code NO_OPERATION when nothing is running.

sl.subgraphs.stop(

): Promise<{ message: string; operationId?: string; status?: string }>

Parameters

hover a row to find it in the code

Required

namerequiredstring

sl.subgraphs.backfill(name, options)

REST POST /api/subgraphs/{name}/backfill source

Process one block range. 409 OPERATION_IN_PROGRESS while another reindex or backfill runs on this subgraph.

sl.subgraphs.backfill(

options: { fromBlock: number; toBlock: number },

): Promise<ReindexResponse>

Parameters

hover a row to find it in the code

Required

`name`requiredstring
`options.fromBlock`requirednumber
`options.toBlock`requirednumber

Returns Promise<ReindexResponse>

message: string
fromBlock: number
toBlock: string | number
operationId: string
status: "queued" | "running" | "cancel_requested"

sl.subgraphs.gaps(name, opts)

REST GET /api/subgraphs/{name}/gaps source

List the block ranges a subgraph is missing.

Each gap has its start, end, size, reason, and when it was detected and resolved. resolved filters to resolved or open gaps; page with limit and offset. meta reports the total gap count and total missing blocks.

sl.subgraphs.gaps(

opts?: { limit?: number; offset?: number; resolved?: boolean },

): Promise<SubgraphGapsResponse>

Parameters

hover a row to find it in the code

Required

namerequiredstring

Options

`opts.limit`number
`opts.offset`number
`opts.resolved`boolean

Returns Promise<SubgraphGapsResponse>

data: SubgraphGapEntry[]
meta: { total: number; totalMissingBlocks: number; limit: number; offset: number }

sl.subgraphs.delete(name, options)

REST DELETE /api/subgraphs/{name}source

Delete a subgraph and its tables.

Permanent. The API cancels any running reindex or backfill first, waits up to 5 seconds for it to stop, then drops the subgraph's tables and registry entry. force: true is sent as ?force=true.

sl.subgraphs.delete(

options?: { force?: boolean },

): Promise<{ message: string }>

Parameters

hover a row to find it in the code

Required

namerequiredstring

Options

options.forceboolean

sl.subgraphs.rows(name, table, params)

REST GET /v1/subgraphs/{name}/{table}source

Read a table's rows, one cursor page at a time.

Anon works on an open instance; pass an apiKey on the client where reads are closed. next_cursor is set on every page that returned rows and is null only on an empty page, so a poller tails with cursor = page.next_cursor ?? cursor. A paging loop ends on an empty page (or one shorter than limit).

sl.subgraphs.rows<T = unknown>(

table: string,

params?: {

limit?: number;

filters?: Record<string, string>;

fields?: string;

order?: string;

sort?: string;

}

& { cursor?: string },

): Promise<SubgraphRowsEnvelope<T>>

Parameters

hover a row to find it in the code

Required

`name`requiredstring
`table`requiredstring

Options

`params.limit`number
`params.filters`Record<string, string>
`params.fields`string
`params.order`string
`params.sort`string
`params.cursor`string

Returns Promise<SubgraphRowsEnvelope<T>>

rows: T[]
next_cursor: Set on every page that returned rows; null only on an empty page.
tip: { block_height: number; subgraph_height: number; blocks_behind: number }

sl.subgraphs.operations(name)

REST GET /api/subgraphs/{name}/operations source

Recent reindex/backfill operations for a subgraph, newest first.

sl.subgraphs.operations(

): Promise<{ operations: SubgraphOperationStatus[] }>

Parameters

hover a row to find it in the code

Required

namerequiredstring

sl.subgraphs.getOperation(name, operationId)

REST GET /api/subgraphs/{name}/operations/{operationId}source

Get the status of one reindex, backfill, or stop operation.

Poll the operationId returned by reindex, backfill, or stop until status is terminal.

sl.subgraphs.getOperation(

operationId: string,

): Promise<SubgraphOperationStatus>

Parameters

hover a row to find it in the code

Required

`name`requiredstring
`operationId`requiredstring

Returns Promise<SubgraphOperationStatus>

id: string
subgraphName: string
kind: "reindex" | "backfill"
status: "queued" | "running" | "completed" | "failed" | "cancelled"
fromBlock: number | null
toBlock: number | null
processedBlocks: number | null
progress: 0–1 fraction; null when no denominator is known yet. 1 when completed.
error: string | null
startedAt: string | null
finishedAt: string | null
createdAt: string
updatedAt: string

sl.subgraphs.deploy(data)

REST POST /api/subgraphs source

Create or update a subgraph. A deploy that needs a rebuild queues one; if a reindex or backfill is already running the API answers 409 with code OPERATION_IN_PROGRESS (an ApiError, not a dedicated class).

sl.subgraphs.deploy(data: DeploySubgraphRequest): Promise<DeploySubgraphResponse>

Parameters

hover a row to find it in the code

Required

`name`requiredstring
`sources`requiredRecord<string, Record<string, unknown>>
`schema`requiredRecord<string, unknown>
`handlerCode`requiredstring

Options

`description`string
`startBlock`number	Override the definition's startBlock for this deploy only.
`sourceCode`string	Original TypeScript source, persisted so chat can read/diff/edit later.
`dryRun`boolean	Validate the definition + print the DDL plan without deploying.

Returns Promise<DeploySubgraphResponse>

action: "created" | "unchanged" | "handler_updated" | "updated" | "reindexed"
subgraphId: string
version: string
message: string
start_block: Effective indexing start height.
operationId: string
reindexStarted: boolean
estimatedEvents: Bounded candidate-event denominator for the reindex just started, when the op was classifiable as sparse/light. Absent for heavy ops (no upfront estimate possible) — check sl subgraphs status after ~30s for a rate-based ETA instead.
warnings: Non-blocking deploy lints (e.g. handler reads a print field never observed on-chain).
pin: sha256 identity of what was deployed; absent on unbundled deploys.
verification: SubgraphVerification
diff: { addedTables: string[]; removedTables: string[]; addedColumns: Record<string, …

sl.subgraphs.getSource(name)

REST GET /api/subgraphs/{name}/sourcesource

Get a deployed subgraph's source.

Returns sourceCode, the bundled handlerCode the runtime executes, and the pin hash of what you deployed. handlerCode and pin are null for local deploys. A subgraph deployed before source was captured returns sourceCode: null and readOnly: true with a reason; redeploy it to capture the source.

sl.subgraphs.getSource(name: string): Promise<SubgraphSource>

Parameters

hover a row to find it in the code

Required

namerequiredstring

Returns Promise<SubgraphSource>

name: string
version: string
sourceCode: string | null
handlerCode: The bundled handler the runtime executes; null for local deploys.
pin: sha256 of pinPreimage; null for local deploys.
pinPreimage: The canonical JSON the pin hashes (handler hash, network, runtime, schema hash, startBlock); null before it was stored.
readOnly: boolean
reason: string
updatedAt: string

sl.subgraphs.bundle(data)

REST POST /api/subgraphs/bundle source

Bundle a TypeScript subgraph source on the server. Used by the web chat authoring loop so Vercel's serverless runtime doesn't have to run esbuild.

sl.subgraphs.bundle(data: { code: string }): Promise<BundleSubgraphResponse>

Parameters

hover a row to find it in the code

Required

coderequiredstring

Returns Promise<BundleSubgraphResponse>

ok: true
name: string
description: string | null
sources: Record<string, Record<string, unknown>>
schema: Record<string, unknown>
handlerCode: string
sourceCode: string
bundleSize: number

sl.subgraphs.count(name, table, params)

REST GET /v1/subgraphs/{name}/{table}/count source

Count the rows in a table that match a filter.

The count is exact. Same auth posture as rows.

sl.subgraphs.count(

table: string,

params?: { filters?: Record<string, string> },

): Promise<{ count: number }>

Parameters

hover a row to find it in the code

Required

`name`requiredstring
`table`requiredstring

Options

params.filtersRecord<string, string>

sl.subgraphs.aggregate(name, table, params)

REST GET /v1/subgraphs/{name}/{table}/aggregate source

Compute scalar aggregates over a table's matching rows.

Same auth posture as rows.

sl.subgraphs.aggregate(

table: string,

params?: SubgraphAggregateParams,

): Promise<SubgraphAggregateResponse>

Parameters

hover a row to find it in the code

Required

`name`requiredstring
`table`requiredstring

Options

`params.filters`Record<string, string>
`params.count`boolean
`params.countDistinct`string[]
`params.sum`string[]
`params.min`string[]
`params.max`string[]

Returns Promise<SubgraphAggregateResponse>

count: number
countDistinct: Record<string, number>
sum: Record<string, string>
min: Record<string, string | null>
max: Record<string, string | null>

sl.subgraphs.typed(def)

source

Returns a typed client for a subgraph defined with defineSubgraph(). Row types are inferred from the subgraph's schema literal types.

sl.subgraphs.typed<T extends { name: string; schema: Record<string, unknown> }>(

def: T,

): InferSubgraphClient<T>

typed.tsts

import { SecondLayer } from "@secondlayer/sdk";

import { defineSubgraph } from "@secondlayer/subgraphs";

const sbtcFlows = defineSubgraph({

startBlock: 8000000,

sources: {

transfers: {

type: "ft_transfer",

assetIdentifier:

"SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token::sbtc-token",

schema: {

transfers: {

columns: {

amount: { type: "uint" },

sender: { type: "principal" },

recipient: { type: "principal" },

handlers: {

transfers: (event, ctx) => {

ctx.insert("transfers", {

amount: event.amount,

sender: event.sender,

recipient: event.recipient,

});

Parameters

hover a row to find it in the code

Required

defrequiredT

Types on this page

BundleSubgraphResponse

A deployed subgraph's bundled sources, schema, and handler code.

DeploySubgraphRequest

The body for deploying a subgraph: sources, schema, and handler code.

DeploySubgraphResponse

What a deploy did, the version, and where indexing starts.

ReindexResponse

A queued reindex and the block range it covers.

SubgraphAgentSchema

A subgraph's tables and columns in a form agents can read.

SubgraphAggregateParams

Request shape for GET /v1/subgraphs/:subgraphName/:tableName/aggregate.

SubgraphAggregateResponse

Aggregate response.

SubgraphDetail

A subgraph's version, pin, status, tables, and sources.

SubgraphGapEntry

start, end, size, reason, detectedAt, resolvedAt

SubgraphGapRange

start, end, size, reason

SubgraphGapsResponse

Missing block ranges in a subgraph, with totals.

SubgraphOperationStatus

Status of a tracked reindex/backfill operation (poll until terminal).

SubgraphRowsEnvelope

/v1 cursor envelope for subgraph table reads.

SubgraphSource

A deployed subgraph's source code, handler bundle, and pin.

SubgraphSpecOptions

Options for generating a subgraph's agent schema.

SubgraphSummary

A subgraph's name, status, and indexing progress.

SubgraphSyncInfo

status, mode, startBlock, lastProcessedBlock, chainTip, sourceChainTip, …

SubgraphVerification

How far a subgraph's rows can be checked without trusting the server, derived from its sources and a scan of its handler.

Edit on GitHub