> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retab.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List Usage Blocks
```python Python theme={null}
from retab import Retab
client = Retab()
# List per-block usage rows
blocks = client.usage.list_blocks(
limit=20,
order="desc",
)
# Filter by workflow and block type
blocks = client.usage.list_blocks(
workflow_id="wf_123",
block_type="extract",
limit=50,
)
for block in blocks.data:
print(block.block_id, block.credits, block.execution_count)
```
```typescript TypeScript theme={null}
import { Retab } from "@retab/node";
const client = new Retab({ apiKey: process.env.RETAB_API_KEY });
// List per-block usage rows
const blocks = await client.usage.list_blocks({
limit: 20,
order: "desc",
});
// Filter by workflow and block type
const filtered = await client.usage.list_blocks({
workflowId: "wf_123",
blockType: "extract",
limit: 50,
});
console.log(blocks.data, filtered.data);
```
```go Go theme={null}
package main
import (
"context"
"fmt"
"log"
retab "github.com/retab-dev/retab/clients/go"
)
func ptr[T any](v T) *T { return &v }
func main() {
ctx := context.Background()
client, err := retab.NewClient("")
if err != nil {
log.Fatal(err)
}
// List per-block usage rows
blocks, err := client.Usage.ListBlocks(ctx, &retab.UsageListBlocksParams{
PaginationParams: retab.PaginationParams{Limit: ptr(20), Order: ptr("desc")},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(blocks)
// Filter by workflow and block type
filtered, err := client.Usage.ListBlocks(ctx, &retab.UsageListBlocksParams{
PaginationParams: retab.PaginationParams{Limit: ptr(50)},
WorkflowID: ptr("wf_123"),
BlockType: ptr("extract"),
})
if err != nil {
log.Fatal(err)
}
fmt.Println(filtered)
}
```
```java Java theme={null}
import com.retab.RetabClient;
public final class Example {
public static void main(String[] args) throws Exception {
RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));
var blocks = client.usage().listBlocks();
System.out.println(blocks);
}
}
```
```curl cURL theme={null}
curl -X 'GET' \
'https://api.retab.com/v1/usage/blocks?limit=20&order=desc' \
-H 'accept: application/json' \
-H 'Authorization: Bearer '
# Filter by workflow and block type
curl -X 'GET' \
'https://api.retab.com/v1/usage/blocks?workflow_id=wf_123&block_type=extract&limit=50' \
-H 'accept: application/json' \
-H 'Authorization: Bearer '
```
```json 200 theme={null}
{
"data": [
{
"block_id": "blk_01G34H8J2K",
"workflow_id": "wf_123",
"block_type": "extract",
"run_count": 42,
"execution_count": 201,
"page_count": 640,
"credits": 512.0,
"status_counts": {
"completed": 190,
"failed": 11
},
"first_activity_at": "2024-03-01T08:00:00Z",
"last_activity_at": "2024-03-15T10:30:12Z"
}
],
"list_metadata": {
"before": null,
"after": "blk_01G34H8J2K"
}
}
```
## OpenAPI
````yaml GET /v1/usage/blocks
openapi: 3.1.0
info:
title: FastAPI
version: 0.1.0
servers:
- url: https://api.retab.com
security: []
paths:
/v1/usage/blocks:
get:
tags:
- Usage
summary: List Usage Blocks
operationId: list_usage_blocks
parameters:
- description: Maximum number of block rows to return.
in: query
name: limit
schema:
type: integer
maximum: 100
minimum: 1
description: Maximum number of block rows to return.
default: 20
title: Limit
required: false
- description: Sort direction on block id.
in: query
name: order
schema:
enum:
- asc
- desc
type: string
description: Sort direction on block id.
default: desc
title: Order
required: false
- description: >-
Return blocks before this cursor (opaque token from a prior page's
list_metadata).
in: query
name: before
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Return blocks before this cursor (opaque token from a prior page's
list_metadata).
title: Before
required: false
- description: >-
Return blocks after this cursor (opaque token from a prior page's
list_metadata).
in: query
name: after
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Return blocks after this cursor (opaque token from a prior page's
list_metadata).
title: After
required: false
- description: Filter to a single workflow id.
in: query
name: workflow_id
schema:
anyOf:
- type: string
- type: 'null'
description: Filter to a single workflow id.
title: Workflow Id
required: false
- description: >-
Filter by block type (e.g. extract, classify, split, parse, edit,
partition).
in: query
name: block_type
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Filter by block type (e.g. extract, classify, split, parse, edit,
partition).
title: Block Type
required: false
- description: Inclusive activity lower bound (YYYY-MM-DD, UTC).
in: query
name: from_date
schema:
anyOf:
- type: string
- type: 'null'
description: Inclusive activity lower bound (YYYY-MM-DD, UTC).
title: From Date
required: false
- description: Inclusive activity upper bound (YYYY-MM-DD, UTC).
in: query
name: to_date
schema:
anyOf:
- type: string
- type: 'null'
description: Inclusive activity upper bound (YYYY-MM-DD, UTC).
title: To Date
required: false
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/UsageBlockList'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
components:
schemas:
UsageBlockList:
properties:
data:
items:
$ref: '#/components/schemas/UsageBlockRecord'
type: array
title: Data
list_metadata:
$ref: '#/components/schemas/ListMetadata'
type: object
required:
- data
- list_metadata
title: UsageBlockList
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
default: []
type: object
title: HTTPValidationError
UsageBlockRecord:
properties:
block_id:
type: string
title: Block Id
block_type:
type: string
title: Block Type
credits:
type: number
title: Credits
execution_count:
type: integer
title: Execution Count
first_activity_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: First Activity At
last_activity_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Last Activity At
page_count:
type: integer
title: Page Count
run_count:
type: integer
title: Run Count
status_counts:
anyOf:
- additionalProperties:
type: integer
type: object
- type: 'null'
title: Status Counts
workflow_id:
type: string
title: Workflow Id
type: object
required:
- block_id
- block_type
- credits
- execution_count
- first_activity_at
- last_activity_at
- page_count
- run_count
- status_counts
- workflow_id
title: UsageBlockRecord
ListMetadata:
properties:
before:
anyOf:
- type: string
- type: 'null'
title: Before
after:
anyOf:
- type: string
- type: 'null'
title: After
type: object
required:
- after
- before
title: ListMetadata
description: Boundary resource IDs for page navigation.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
default: null
ctx:
type: object
title: Context
default: {}
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
````