> ## 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 Runs
```python Python theme={null}
from retab import Retab
client = Retab()
# List recent workflow-run usage rows
runs = client.usage.list_runs(
limit=20,
order="desc",
)
# Filter by workflow and date range
runs = client.usage.list_runs(
workflow_id="wf_123",
from_date="2024-01-01",
to_date="2024-12-31",
limit=50,
)
for run in runs.data:
print(run.run_id, run.credits, run.page_count)
```
```typescript TypeScript theme={null}
import { Retab } from "@retab/node";
const client = new Retab({ apiKey: process.env.RETAB_API_KEY });
// List recent workflow-run usage rows
const runs = await client.usage.list_runs({
limit: 20,
order: "desc",
});
// Filter by workflow and date range
const filtered = await client.usage.list_runs({
workflowId: "wf_123",
fromDate: "2024-01-01",
toDate: "2024-12-31",
limit: 50,
});
console.log(runs.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 recent workflow-run usage rows
runs, err := client.Usage.ListRuns(ctx, &retab.UsageListRunsParams{
PaginationParams: retab.PaginationParams{Limit: ptr(20), Order: ptr("desc")},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(runs)
// Filter by workflow and date range
filtered, err := client.Usage.ListRuns(ctx, &retab.UsageListRunsParams{
PaginationParams: retab.PaginationParams{Limit: ptr(50)},
WorkflowID: ptr("wf_123"),
FromDate: ptr("2024-01-01"),
ToDate: ptr("2024-12-31"),
})
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 runs = client.usage().listRuns();
System.out.println(runs);
}
}
```
```curl cURL theme={null}
curl -X 'GET' \
'https://api.retab.com/v1/usage/runs?limit=20&order=desc' \
-H 'accept: application/json' \
-H 'Authorization: Bearer '
# Filter by workflow and date range
curl -X 'GET' \
'https://api.retab.com/v1/usage/runs?workflow_id=wf_123&from_date=2024-01-01&to_date=2024-12-31&limit=50' \
-H 'accept: application/json' \
-H 'Authorization: Bearer '
```
```json 200 theme={null}
{
"data": [
{
"run_id": "run_01G34H8J2K",
"workflow_id": "wf_123",
"status": "completed",
"trigger_type": "api",
"created_at": "2024-03-15T10:30:00Z",
"started_at": "2024-03-15T10:30:01Z",
"completed_at": "2024-03-15T10:30:12Z",
"duration_ms": 11000,
"page_count": 8,
"credits": 12.5,
"retry_count": 0,
"execution_duration_ms": 9400
}
],
"list_metadata": {
"before": null,
"after": "run_01G34H8J2K"
}
}
```
## OpenAPI
````yaml GET /v1/usage/runs
openapi: 3.1.0
info:
title: FastAPI
version: 0.1.0
servers:
- url: https://api.retab.com
security: []
paths:
/v1/usage/runs:
get:
tags:
- Usage
summary: List Usage Runs
operationId: list_usage_runs
parameters:
- description: Maximum number of run rows to return.
in: query
name: limit
schema:
type: integer
maximum: 100
minimum: 1
description: Maximum number of run rows to return.
default: 20
title: Limit
required: false
- description: Sort direction on run created_at.
in: query
name: order
schema:
enum:
- asc
- desc
type: string
description: Sort direction on run created_at.
default: desc
title: Order
required: false
- description: Return runs before this run id (keyset cursor).
in: query
name: before
schema:
anyOf:
- type: string
- type: 'null'
description: Return runs before this run id (keyset cursor).
title: Before
required: false
- description: Return runs after this run id (keyset cursor).
in: query
name: after
schema:
anyOf:
- type: string
- type: 'null'
description: Return runs after this run id (keyset cursor).
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 lifecycle status: pending, queued, running, completed,
error, failed, awaiting_review, or cancelled.
in: query
name: status
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Filter by lifecycle status: pending, queued, running, completed,
error, failed, awaiting_review, or cancelled.
title: Status
required: false
- description: >-
Filter by trigger type: manual, api, schedule, webhook, email, or
restart.
in: query
name: trigger_type
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Filter by trigger type: manual, api, schedule, webhook, email, or
restart.
title: Trigger Type
required: false
- description: Inclusive created_at lower bound (YYYY-MM-DD, UTC).
in: query
name: from_date
schema:
anyOf:
- type: string
- type: 'null'
description: Inclusive created_at lower bound (YYYY-MM-DD, UTC).
title: From Date
required: false
- description: Inclusive created_at upper bound (YYYY-MM-DD, UTC).
in: query
name: to_date
schema:
anyOf:
- type: string
- type: 'null'
description: Inclusive created_at upper bound (YYYY-MM-DD, UTC).
title: To Date
required: false
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/UsageRunList'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
components:
schemas:
UsageRunList:
properties:
data:
items:
$ref: '#/components/schemas/UsageRunRecord'
type: array
title: Data
list_metadata:
$ref: '#/components/schemas/ListMetadata'
type: object
required:
- data
- list_metadata
title: UsageRunList
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
default: []
type: object
title: HTTPValidationError
UsageRunRecord:
properties:
completed_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Completed At
created_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created At
credits:
type: number
title: Credits
duration_ms:
anyOf:
- type: integer
- type: 'null'
title: Duration Ms
execution_duration_ms:
type: integer
title: Execution Duration Ms
page_count:
type: integer
title: Page Count
retry_count:
type: integer
title: Retry Count
run_id:
type: string
title: Run Id
started_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Started At
status:
type: string
title: Status
trigger_type:
type: string
title: Trigger Type
workflow_id:
type: string
title: Workflow Id
type: object
required:
- completed_at
- created_at
- credits
- duration_ms
- execution_duration_ms
- page_count
- retry_count
- run_id
- started_at
- status
- trigger_type
- workflow_id
title: UsageRunRecord
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
````