Skip to main content
GET
https://app.commodityai.com
/
api
/
v1
/
sources
/
{id}
/
records
curl -X GET "https://app.commodityai.com/api/v1/sources/123e4567-e89b-12d3-a456-426614174000/records?limit=50" \
  -H "Authorization: Bearer cai_live_your_api_key_here"

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "definition_id": "123e4567-e89b-12d3-a456-426614174000",
      "definition_name": "invoices",
      "record_data": {
        "invoice_number": "INV-2024-001",
        "amount": 1250.00,
        "due_date": "2024-02-15",
        "vendor": "Acme Corporation"
      },
      "metadata": {
        "review_status": "approved",
        "confidence_score": 0.95
      },
      "created_at": "2024-01-20T15:30:00Z",
      "updated_at": "2024-01-21T09:15:00Z"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "definition_id": "123e4567-e89b-12d3-a456-426614174000",
      "definition_name": "invoices",
      "record_data": {
        "invoice_number": "INV-2024-002",
        "amount": 875.50,
        "due_date": "2024-02-20",
        "vendor": "Beta Industries"
      },
      "metadata": {
        "review_status": "pending",
        "confidence_score": 0.87
      },
      "created_at": "2024-01-19T11:45:00Z",
      "updated_at": "2024-01-19T11:45:00Z"
    }
  ],
  "meta": {
    "has_more": true,
    "next_cursor": "eyJpZCI6IjY2MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMSJ9",
    "limit": 50
  }
}
Returns a paginated list of source records for a specific definition. Source records are extracted from documents processed through your workflows.

​
Path Parameters

​
id
string
required
The unique identifier (UUID) of the source record definition

​
Query Parameters

​
limit
number
default:"100"
Number of records to return (max: 1000)
​
cursor
string
Pagination cursor for fetching the next page of results

​
Advanced Filtering

​
record_counter[operator]
number
Filter by record counter with comparison operatorsSupported operators: eq, gt, gte, lt, lteExamples:
  • record_counter[gte]=5 - Records with counter >= 5
  • record_counter[lt]=100 - Records with counter < 100
​
created_at[operator]
string
Filter by creation timestamp (ISO 8601 format)Supported operators: eq, gt, gte, lt, lteExamples:
  • created_at[gte]=2024-01-01T00:00:00Z - Created on or after Jan 1, 2024
  • created_at[lt]=2024-12-31T23:59:59Z - Created before Dec 31, 2024
​
updated_at[operator]
string
Filter by last update timestamp (ISO 8601 format)Supported operators: eq, gt, gte, lt, lteExample:
  • updated_at[gte]=2024-01-01T00:00:00Z - Updated on or after Jan 1, 2024

​
Request Examples

curl -X GET "https://app.commodityai.com/api/v1/sources/123e4567-e89b-12d3-a456-426614174000/records?limit=50" \
  -H "Authorization: Bearer cai_live_your_api_key_here"

​
Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "definition_id": "123e4567-e89b-12d3-a456-426614174000",
      "definition_name": "invoices",
      "record_data": {
        "invoice_number": "INV-2024-001",
        "amount": 1250.00,
        "due_date": "2024-02-15",
        "vendor": "Acme Corporation"
      },
      "metadata": {
        "review_status": "approved",
        "confidence_score": 0.95
      },
      "created_at": "2024-01-20T15:30:00Z",
      "updated_at": "2024-01-21T09:15:00Z"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "definition_id": "123e4567-e89b-12d3-a456-426614174000",
      "definition_name": "invoices",
      "record_data": {
        "invoice_number": "INV-2024-002",
        "amount": 875.50,
        "due_date": "2024-02-20",
        "vendor": "Beta Industries"
      },
      "metadata": {
        "review_status": "pending",
        "confidence_score": 0.87
      },
      "created_at": "2024-01-19T11:45:00Z",
      "updated_at": "2024-01-19T11:45:00Z"
    }
  ],
  "meta": {
    "has_more": true,
    "next_cursor": "eyJpZCI6IjY2MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMSJ9",
    "limit": 50
  }
}

​
Response Fields

​
data
array
Array of source record objects
​
meta
object
Pagination metadata

​
Response Headers

All successful responses include rate limit headers to help you monitor your API usage:
​
X-RateLimit-Limit-Minute
number
Maximum number of requests allowed per minute (100)
​
X-RateLimit-Remaining-Minute
number
Number of requests remaining in the current minute
​
X-RateLimit-Reset-Minute
number
Unix timestamp (in seconds) when the per-minute limit resets
​
X-RateLimit-Limit-Day
number
Maximum number of requests allowed per day (10,000)
​
X-RateLimit-Remaining-Day
number
Number of requests remaining in the current day
​
X-RateLimit-Reset-Day
number
Unix timestamp (in seconds) when the daily limit resets
For more information on rate limits and how to handle them, see Rate Limits.

​
Pagination

To paginate through results:
  1. Make an initial request without a cursor parameter
  2. Check meta.has_more in the response
  3. If true, use meta.next_cursor in your next request’s cursor parameter
  4. Repeat until has_more is false
Example pagination flow: 
const definitionId = '123e4567-e89b-12d3-a456-426614174000';
let cursor = null;
let allRecords = [];

do {
  const params = new URLSearchParams({
    limit: '100'
  });

  if (cursor) {
    params.append('cursor', cursor);
  }

  const response = await fetch(
    `https://app.commodityai.com/api/v1/sources/${definitionId}/records?${params}`,
    {
      headers: { 'Authorization': 'Bearer cai_live_your_api_key_here' }
    }
  );

  const data = await response.json();
  allRecords.push(...data.data);
  cursor = data.meta.has_more ? data.meta.next_cursor : null;

} while (cursor);

console.log(`Fetched ${allRecords.length} total records`);

​
Error Codes

StatusCodeDescription
400validation_errorInvalid query parameters or filter operators
401unauthorizedInvalid or missing API key
404not_foundSource record definition not found with the provided ID
429rate_limit_exceededToo many requests (see Rate Limits)
500internal_errorInternal server error