ShotGrid Asset Query Performance: Filtering and Pagination Decision Guide

Decision: How to Query ShotGrid Assets Without Hitting Rate Limits

In a ShotGrid site with thousands of assets, an unfiltered Asset query can scan the entire database, return a large payload, and consume many paginated requests. ShotGrid applies a rate limit of 100 requests per minute per API user. The practical decision is whether to filter server-side by project and status, select only needed columns, and paginate explicitly, or to retrieve broad result sets and filter them locally.

Constraints

• ShotGrid HTTP API endpoint: /api/v1/query.
• Default page size is typically 100 items; specify page_size explicitly because pagination behavior changed in ShotGrid 2024.2.
• Rate limit: 100 requests per minute per user; a 5,000-asset unfiltered result could require more than 50 paginated calls.
• The cache parameter appeared as experimental in ShotGrid 2024.1 and may be disabled or changed without notice; treat it as unverified for production.

Supported Query Options

Option	Expected behavior	Complexity	Best for
Unfiltered query, client-side filtering	Scans all assets in site; high payload; many pages	Low	Sites under roughly 1,000 assets
Project filter only	Limits scan to one project; smaller payload	Low	Project-specific tools and dashboards
Project + sg_status_list filter	Narrows to active assets; fewest pages	Low	Artist task lists and active-shot reviews
Project + status + explicit fields	Returns only requested columns such as code, status, image path	Low	UI widgets and metadata exports
Experimental cache parameter	Server-side caching for identical repeated queries; stability not guaranteed	Medium	Read-only repeated lookups, non-critical workflows

Trade-Offs

Server-side filtering moves the work to ShotGrid and reduces the number of API pages your client must request. Selecting fewer fields with fields lowers payload size and parsing time, but omits any data you do not request, so downstream code must handle missing keys.

Client-side filtering is simpler to write but wastes rate-limit budget. If your query returns 5,000 assets at 100 per page, that is 50 requests just to fetch the data, leaving little room for other API calls in the same minute.

The experimental cache may speed up identical repeated queries, but because it can be disabled or altered without notice, do not build critical pipeline logic around it without a fallback to uncached queries.

Concrete Implementation: Filtered Asset Query

Run this from a terminal or CI job that can reach your ShotGrid instance. You need a valid ShotGrid API token or script key with permission to read Asset entities in the target project.

curl -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -d '{
    "targets": ["Asset"],
    "filters": [
      ["project", "is", {"type": "Project", "id": YOUR_PROJECT_ID}],
      ["sg_status_list", "in", ["ip", "rev", "fin"]]
    ],
    "fields": ["code", "sg_status_list", "image"],
    "page_size": 100,
    "order": [{"field": "code", "direction": "asc"}]
  }' \
  https://YOUR_SHOTGRID_SITE.shotgrid.autodesk.com/api/v1/query

Replace YOUR_ACCESS_TOKEN, YOUR_PROJECT_ID, and the site hostname. The image field returns the thumbnail path; sg_status_list uses ShotGrid status short names such as ip for in progress, rev for review, and fin for finished.

Validation Steps

1. Inspect rate-limit headers: Run curl -i and check X-RateLimit-Remaining. It should decrement by approximately one per request and stay well above zero.
2. Measure response time: Use time curl ... and confirm the filtered query completes in a few seconds under normal load; times over five seconds suggest missing or ineffective filters.
3. Verify pagination math: Confirm the response total and pages fields satisfy pages = ceil(total / page_size).
4. Compare with and without project filter: Run the same query without the project filter in a large database and compare response size and duration. The unfiltered version should be slower and return more pages.

Limitations

ShotGrid 2024.2 changed pagination handling, so older client libraries may report inconsistent page counts. Always pass page_size explicitly and do not rely on defaults. The cache parameter is experimental; verify current support with your ShotGrid administrator before using it in automation. Do not store access tokens in shell history or scripts shared across teams.

There is no rollback for this operation because it is a read-only query. To confirm the result, check that the returned asset codes match assets visible in the ShotGrid web interface for the same project and statuses.