[Server] How to See Recent Builds via API?

You can leverage an admin API endpoint to see recent builds on your CircleCI Server.

Prerequisites

• You need to be an admin user on the Server instance.
• You will need a User API token. The token can be generated from https://app.${CIRCLE_HOSTNAME}/settings/user/tokens 

Usage

You can leverage the admin API endpoint as follows:

• To view the "most recent 10 builds":

curl -H "Circle-Token: $CIRCLE_TOKEN" \
"https://$CIRCLE_HOSTNAME/api/v1/admin/recent-builds?limit=10"

• To view only "running" builds:

curl -H "Circle-Token: $CIRCLE_TOKEN" \
  "https://$CIRCLE_HOSTNAME/api/v1/admin/recent-builds?status=running"

• To fetch "queued" builds (JSON summary):

curl -sS -f -H "Circle-Token: $CIRCLE_TOKEN" \
  "https://$CIRCLE_HOSTNAME/api/v1/admin/recent-builds?status=queued&limit=10" \
  | jq '{total:length, oldest:(map(select(.queued_at))|min_by(.queued_at)|{build_url,queued_at}), builds:map({build_url,queued_at})}'

• To see how many "queued" or if you have 1000 queued builds:

curl -sS -f -H "Circle-Token: $CIRCLE_TOKEN" \
  "https://$CIRCLE_HOSTNAME/api/v1/admin/recent-builds?status=queued&limit=10" \
  | jq '{
      total: length,
      oldest: (map(select(.queued_at)) 
               | min_by(.queued_at) 
               | {build_url, queued_at}),
      builds: map({build_url, queued_at})
    }'

Considerations:

• There is no enforced maximum for the limit parameter.  
• Using a very large limit can cause timeouts or degraded performance.  
• For lightweight usage (e.g., occasional curl calls for inspection), no special configuration is needed.
• For heavy or automated usage (e.g., thousands of requests per minute, such as 25,000+/min), reach out to CircleCI Support or your Account Team for guidance.  
• In some cases, right-sizing resources may be required to ensure reliability when hitting this endpoint at scale.