List Object Records

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

{
  "data": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "definition_id": "234e4567-e89b-12d3-a456-426614174111",
      "definition_name": "contracts",
      "primary_key_hash": "abc123def456",
      "record_counter": 42,
      "record_data": {
        "contract_number": "CON-2024-042",
        "counterparty": "Global Trading LLC",
        "commodity": "Soybeans",
        "quantity": 50000,
        "price_per_unit": 12.50,
        "delivery_date": "2024-03-15"
      },
      "metadata": {
        "record_identifier": "CON-2024-042",
        "status": "active"
      },
      "created_at": "2024-01-20T15:30:00Z",
      "updated_at": "2024-01-21T09:15:00Z"
    },
    {
      "id": "880e8400-e29b-41d4-a716-446655440003",
      "definition_id": "234e4567-e89b-12d3-a456-426614174111",
      "definition_name": "contracts",
      "primary_key_hash": "xyz789uvw012",
      "record_counter": 43,
      "record_data": {
        "contract_number": "CON-2024-043",
        "counterparty": "Midwest Grain Co",
        "commodity": "Corn",
        "quantity": 75000,
        "price_per_unit": 4.25,
        "delivery_date": "2024-04-01"
      },
      "metadata": {
        "record_identifier": "CON-2024-043",
        "status": "active"
      },
      "created_at": "2024-01-21T10:15:00Z",
      "updated_at": "2024-01-21T10:15:00Z"
    }
  ],
  "meta": {
    "has_more": true,
    "next_cursor": "eyJpZCI6Ijg4MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMyJ9",
    "limit": 50
  }
}

GET

https://app.commodityai.com

api

objects

{id}

records

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

{
  "data": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "definition_id": "234e4567-e89b-12d3-a456-426614174111",
      "definition_name": "contracts",
      "primary_key_hash": "abc123def456",
      "record_counter": 42,
      "record_data": {
        "contract_number": "CON-2024-042",
        "counterparty": "Global Trading LLC",
        "commodity": "Soybeans",
        "quantity": 50000,
        "price_per_unit": 12.50,
        "delivery_date": "2024-03-15"
      },
      "metadata": {
        "record_identifier": "CON-2024-042",
        "status": "active"
      },
      "created_at": "2024-01-20T15:30:00Z",
      "updated_at": "2024-01-21T09:15:00Z"
    },
    {
      "id": "880e8400-e29b-41d4-a716-446655440003",
      "definition_id": "234e4567-e89b-12d3-a456-426614174111",
      "definition_name": "contracts",
      "primary_key_hash": "xyz789uvw012",
      "record_counter": 43,
      "record_data": {
        "contract_number": "CON-2024-043",
        "counterparty": "Midwest Grain Co",
        "commodity": "Corn",
        "quantity": 75000,
        "price_per_unit": 4.25,
        "delivery_date": "2024-04-01"
      },
      "metadata": {
        "record_identifier": "CON-2024-043",
        "status": "active"
      },
      "created_at": "2024-01-21T10:15:00Z",
      "updated_at": "2024-01-21T10:15:00Z"
    }
  ],
  "meta": {
    "has_more": true,
    "next_cursor": "eyJpZCI6Ijg4MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMyJ9",
    "limit": 50
  }
}

Returns a paginated list of object records for a specific definition. Objects are user-defined data structures built from your source records.

Path Parameters

string

required

The unique identifier (UUID) of the object 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]=10 - Records with counter >= 10
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/objects/234e4567-e89b-12d3-a456-426614174111/records?limit=50" \
  -H "Authorization: Bearer cai_live_your_api_key_here"

Response

{
  "data": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "definition_id": "234e4567-e89b-12d3-a456-426614174111",
      "definition_name": "contracts",
      "primary_key_hash": "abc123def456",
      "record_counter": 42,
      "record_data": {
        "contract_number": "CON-2024-042",
        "counterparty": "Global Trading LLC",
        "commodity": "Soybeans",
        "quantity": 50000,
        "price_per_unit": 12.50,
        "delivery_date": "2024-03-15"
      },
      "metadata": {
        "record_identifier": "CON-2024-042",
        "status": "active"
      },
      "created_at": "2024-01-20T15:30:00Z",
      "updated_at": "2024-01-21T09:15:00Z"
    },
    {
      "id": "880e8400-e29b-41d4-a716-446655440003",
      "definition_id": "234e4567-e89b-12d3-a456-426614174111",
      "definition_name": "contracts",
      "primary_key_hash": "xyz789uvw012",
      "record_counter": 43,
      "record_data": {
        "contract_number": "CON-2024-043",
        "counterparty": "Midwest Grain Co",
        "commodity": "Corn",
        "quantity": 75000,
        "price_per_unit": 4.25,
        "delivery_date": "2024-04-01"
      },
      "metadata": {
        "record_identifier": "CON-2024-043",
        "status": "active"
      },
      "created_at": "2024-01-21T10:15:00Z",
      "updated_at": "2024-01-21T10:15:00Z"
    }
  ],
  "meta": {
    "has_more": true,
    "next_cursor": "eyJpZCI6Ijg4MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMyJ9",
    "limit": 50
  }
}

Response Fields

data

array

Array of object record objects

Show object record

string

Unique identifier for the object record (UUID)

definition_id

string

ID of the object definition this record belongs to

definition_name

string

Name of the object definition (e.g., “contracts”, “shipments”)

primary_key_hash

string

Hash of the record’s primary key fields, used for deduplication

record_counter

number

Auto-incrementing counter for this record within its definition

record_data

object

The actual field values for this record. Structure varies based on the definition’s schema.

metadata

object

Additional metadata about the record (identifiers, status, etc.)

created_at

string

ISO 8601 timestamp when the record was created

updated_at

string

ISO 8601 timestamp when the record was last modified

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:

Make an initial request without a cursor parameter
Check meta.has_more in the response
If true, use meta.next_cursor in your next request’s cursor parameter
Repeat until has_more is false

Example pagination flow:

const definitionId = '234e4567-e89b-12d3-a456-426614174111';
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/objects/${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

Status	Code	Description
`400`	`validation_error`	Invalid query parameters or filter operators
`401`	`unauthorized`	Invalid or missing API key
`404`	`not_found`	Object definition not found with the provided ID
`429`	`rate_limit_exceeded`	Too many requests (see Rate Limits)
`500`	`internal_error`	Internal server error

List Source Records Rate Limits

⌘I

Authentication

Records

Limits & Errors

Path Parameters

Query Parameters

Advanced Filtering

Request Examples

Response

Response Fields

Response Headers

Error Codes

Authentication

Records

Limits & Errors

​Path Parameters

​Query Parameters

​Advanced Filtering

​Request Examples

​Response

​Response Fields

​Response Headers

​Pagination

​Error Codes

Path Parameters

Query Parameters

Advanced Filtering

Request Examples

Response

Response Fields

Response Headers

Pagination

Error Codes