Query Optimization

Fields & Filtering

Request only the data you need. Reduce payload size, improve performance, and minimize bandwidth with field selection and powerful filtering.

-70%

Payload reduction with field selection

Filter operators supported

23ms

Average full-text search time

Field Selection

Select Fields to Include

Generated Query

GET /v2/valuations

?fields=id,price_min,price_max,brand

Sample Response

{
  "data": [
    {
      "id": "val_K7j9mNpQ",
      "price_min": 1450,
      "price_max": 1850,
      "brand": "Louis Vuitton"
    }
  ]
}

4 of 10 fields~60% smaller

Code Examples

Field Selection

# Select only specific fields
curl "https://api.justkalm.com/v2/valuations?fields=id,price_min,price_max,brand" \
  -H "Authorization: Bearer jk_live_xxx"

# Response with only requested fields
{
  "data": [
    {
      "id": "val_K7j9mNpQ",
      "price_min": 1450,
      "price_max": 1850,
      "brand": "Louis Vuitton"
    }
  ]
}

Expand Nested Objects

# Expand nested objects
curl "https://api.justkalm.com/v2/valuations/val_K7j9mNpQ?expand=metadata,comparables" \
  -H "Authorization: Bearer jk_live_xxx"

# Response with expanded objects
{
  "id": "val_K7j9mNpQ",
  "price_min": 1450,
  "metadata": {
    "materials": ["canvas", "leather"],
    "year": 2023,
    "size": "MM",
    "color": "Monogram"
  },
  "comparables": [
    { "id": "comp_001", "sold_price": 1520, "date": "2024-01-10" },
    { "id": "comp_002", "sold_price": 1680, "date": "2024-01-08" }
  ]
}

Filter Operators

# Filter valuations by criteria
curl "https://api.justkalm.com/v2/valuations?\
brand=Louis+Vuitton&\
category=bags&\
price_min[gte]=1000&\
price_max[lte]=2000&\
created_at[gte]=2024-01-01" \
  -H "Authorization: Bearer jk_live_xxx"

# Filter operators:
# [eq]   Equal (default if omitted)
# [ne]   Not equal
# [gt]   Greater than
# [gte]  Greater than or equal
# [lt]   Less than
# [lte]  Less than or equal
# [in]   In array (comma-separated)
# [nin]  Not in array

Full-Text Search

# Full-text search
curl "https://api.justkalm.com/v2/valuations?\
q=neverfull+monogram&\
search_fields=title,brand,description" \
  -H "Authorization: Bearer jk_live_xxx"

# Response with relevance scores
{
  "data": [...],
  "meta": {
    "query": "neverfull monogram",
    "total_matches": 47,
    "search_time_ms": 23
  }
}

Filter Operators Reference

Operator	Description	Example	SQL Equivalent
[eq]	Equal to	brand[eq]=Chanel	brand = "Chanel"
[ne]	Not equal to	status[ne]=pending	status != "pending"
[gt]	Greater than	price_min[gt]=500	price_min > 500
[gte]	Greater or equal	confidence[gte]=80	confidence >= 80
[lt]	Less than	price_max[lt]=1000	price_max < 1000
[lte]	Less or equal	created_at[lte]=2024-01-01	created_at <= ...
[in]	In array	brand[in]=LV,Gucci,Prada	brand IN (...)
[nin]	Not in array	category[nin]=shoes,hats	category NOT IN (...)

Best Practices

Always Use Field Selection

Only request fields you need. A response with 4 fields is 70% smaller than all 10+ fields.

Expand Only When Needed

Nested objects like metadata and comparables add latency. Only expand for detail views.

Combine Filters Wisely

Multiple filters use AND logic. For OR queries, use the [in] operator or make separate requests.

Index-Aware Filtering

Filters on id, brand, category, and created_at are indexed. These are fastest for large datasets.

Optimize Your Queries

Try field selection and filtering in the API playground.

API Playground Caching Guide