> ## 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 Primitives
```python Python theme={null}
from retab import Retab
client = Retab()
# List per-operation usage rows
primitives = client.usage.list_primitives(
limit=20,
order="desc",
)
# Filter by operation, project, and date range
primitives = client.usage.list_primitives(
operation="extraction",
project_id="proj_123",
from_date="2024-01-01",
to_date="2024-12-31",
limit=50,
)
for primitive in primitives.data:
print(primitive.primitive_execution_id, primitive.operation, primitive.credits)
```
```typescript TypeScript theme={null}
import { Retab } from "@retab/node";
const client = new Retab({ apiKey: process.env.RETAB_API_KEY });
// List per-operation usage rows
const primitives = await client.usage.list_primitives({
limit: 20,
order: "desc",
});
// Filter by operation, project, and date range
const filtered = await client.usage.list_primitives({
operation: "extraction",
projectId: "proj_123",
fromDate: "2024-01-01",
toDate: "2024-12-31",
limit: 50,
});
console.log(primitives.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-operation usage rows
primitives, err := client.Usage.ListPrimitives(ctx, &retab.UsageListPrimitivesParams{
PaginationParams: retab.PaginationParams{Limit: ptr(20), Order: ptr("desc")},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(primitives)
// Filter by operation, project, and date range
filtered, err := client.Usage.ListPrimitives(ctx, &retab.UsageListPrimitivesParams{
PaginationParams: retab.PaginationParams{Limit: ptr(50)},
Operation: ptr("extraction"),
ProjectID: ptr("proj_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 primitives = client.usage().listPrimitives();
System.out.println(primitives);
}
}
```
```curl cURL theme={null}
curl -X 'GET' \
'https://api.retab.com/v1/usage/primitives?limit=20&order=desc' \
-H 'accept: application/json' \
-H 'Authorization: Bearer '
# Filter by operation, project, and date range
curl -X 'GET' \
'https://api.retab.com/v1/usage/primitives?operation=extraction&project_id=proj_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": [
{
"primitive_execution_id": "pex_01G34H8J2K",
"operation": "extraction",
"workflow_id": "wf_123",
"run_id": "run_01G34H8J2K",
"project_id": "proj_123",
"block_id": "blk_01G34H8J2K",
"status": "completed",
"resource_kind": "extraction",
"model": "retab-large",
"created_at": "2024-03-15T10:30:00Z",
"completed_at": "2024-03-15T10:30:12Z",
"duration_ms": 12000,
"page_count": 8,
"credits": 12.5,
"documents": [
{
"file_id": "file_6dd6eb00688ad8d1",
"filename": "invoice.pdf"
}
],
"metadata": {
"tenant": "acme"
}
}
],
"list_metadata": {
"before": null,
"after": "pex_01G34H8J2K"
}
}
```
## OpenAPI
````yaml GET /v1/usage/primitives
openapi: 3.1.0
info:
title: FastAPI
version: 0.1.0
servers:
- url: https://api.retab.com
security: []
paths:
/v1/usage/primitives:
get:
tags:
- Usage
summary: List Usage Primitives
operationId: list_usage_primitives
parameters:
- description: Maximum number of execution rows to return.
in: query
name: limit
schema:
type: integer
maximum: 100
minimum: 1
description: Maximum number of execution rows to return.
default: 20
title: Limit
required: false
- description: Sort direction on execution created_at.
in: query
name: order
schema:
enum:
- asc
- desc
type: string
description: Sort direction on execution created_at.
default: desc
title: Order
required: false
- description: >-
Return executions before this primitive-execution id (keyset
cursor).
in: query
name: before
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Return executions before this primitive-execution id (keyset
cursor).
title: Before
required: false
- description: Return executions after this primitive-execution id (keyset cursor).
in: query
name: after
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Return executions after this primitive-execution id (keyset
cursor).
title: After
required: false
- description: >-
Scope the export to this environment id within the caller's
organization. Defaults to the authenticated identity's environment.
in: query
name: environment_id
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Scope the export to this environment id within the caller's
organization. Defaults to the authenticated identity's
environment.
title: Environment Id
required: false
- description: Filter to a single workflow id (origin workflow).
in: query
name: workflow_id
schema:
anyOf:
- type: string
- type: 'null'
description: Filter to a single workflow id (origin workflow).
title: Workflow Id
required: false
- description: Filter to executions owned by a single project id.
in: query
name: project_id
schema:
anyOf:
- type: string
- type: 'null'
description: Filter to executions owned by a single project id.
title: Project Id
required: false
- description: Filter to a single workflow run id (origin run).
in: query
name: run_id
schema:
anyOf:
- type: string
- type: 'null'
description: Filter to a single workflow run id (origin run).
title: Run Id
required: false
- description: Filter to a single workflow block id (origin block).
in: query
name: block_id
schema:
anyOf:
- type: string
- type: 'null'
description: Filter to a single workflow block id (origin block).
title: Block Id
required: false
- description: >-
Filter by operation (extraction, classify, split, parse, edit,
schema_generation).
in: query
name: operation
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Filter by operation (extraction, classify, split, parse, edit,
schema_generation).
title: Operation
required: false
- description: Filter by execution lifecycle status.
in: query
name: status
schema:
anyOf:
- type: string
- type: 'null'
description: Filter by execution lifecycle status.
title: Status
required: false
- description: >-
Filter by metadata equality: a JSON object of string key/value pairs
(e.g. {"tenant":"acme"}). Pairs AND together.
in: query
name: metadata
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Filter by metadata equality: a JSON object of string key/value
pairs (e.g. {"tenant":"acme"}). Pairs AND together.
title: Metadata
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/UsagePrimitiveList'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
components:
schemas:
UsagePrimitiveList:
properties:
data:
items:
$ref: '#/components/schemas/UsagePrimitiveRecord'
type: array
title: Data
list_metadata:
$ref: '#/components/schemas/ListMetadata'
type: object
required:
- data
- list_metadata
title: UsagePrimitiveList
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
default: []
type: object
title: HTTPValidationError
UsagePrimitiveRecord:
properties:
block_id:
anyOf:
- type: string
- type: 'null'
title: Block Id
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
documents:
anyOf:
- items:
$ref: '#/components/schemas/UsagePrimitiveDocument'
type: array
- type: 'null'
title: Documents
duration_ms:
anyOf:
- type: integer
- type: 'null'
title: Duration Ms
metadata:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Metadata
model:
anyOf:
- type: string
- type: 'null'
title: Model
operation:
type: string
title: Operation
page_count:
type: integer
title: Page Count
primitive_execution_id:
type: string
title: Primitive Execution Id
project_id:
anyOf:
- type: string
- type: 'null'
title: Project Id
resource_kind:
anyOf:
- type: string
- type: 'null'
title: Resource Kind
run_id:
anyOf:
- type: string
- type: 'null'
title: Run Id
status:
type: string
title: Status
workflow_id:
anyOf:
- type: string
- type: 'null'
title: Workflow Id
type: object
required:
- block_id
- completed_at
- created_at
- credits
- documents
- duration_ms
- metadata
- model
- operation
- page_count
- primitive_execution_id
- project_id
- resource_kind
- run_id
- status
- workflow_id
title: UsagePrimitiveRecord
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
UsagePrimitiveDocument:
properties:
file_id:
anyOf:
- type: string
- type: 'null'
title: File Id
filename:
anyOf:
- type: string
- type: 'null'
title: Filename
type: object
required:
- file_id
- filename
title: UsagePrimitiveDocument
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
````