How to show recent builds for a tag, in APIv1.1

In API v1.1, I can list recent builds on a project at:

I can also list all recent builds for a particular branch like this:

We have a project that builds whenever a new git tag is pushed to the corresponding github project. These builds have no branch name. They show up in the CircleCI web UI with the tag name where the branch name would be. When I list these jobs using the API, they show the value of branch as “null”.

I can’t seem to find any way to list these builds, unless they happen to be the most recent builds for the project, in which case I can just list all recent builds for the project (as in my first URL above). But if the most tag builds I’m looking for aren’t recent and there are many master or branch builds more recently, then the tag builds don’t show up at all.

I’ve tried things like this, but they always return an empty list:

I see a post in the forum suggesting that the latter used to work, but stopped working several years ago, and unfortunately nobody from CircleCI responded:

How can I list the most recent builds (or all builds) for a particular tag? Or even, show the most recent builds for all tags, or all builds for branch “null”?

1 Like

I opened a support case about this last summer or fall, and someone from CircleCI support answered that you cannot list builds by tag, and that they were not planning to add such a feature to API v1, but could give me no estimate about when API v2 would be available on CircleCI server. As of now, over 8 months later, I believe it is still not available.

:wave: @cos,

Although it’s not (yet) possible to pass a tag as a query parameter to retrieve all pipelines associated with a specific tag, you can list those using the " Get all pipelines" API v2 endpoint and a JSON processor (jq).

curl --location --request GET '{project-slug}/pipeline' \
--header 'Circle-Token: your_personal_API_token' | jq -s '.[] | .items[] | select(.vcs.tag == "your_tag")'


curl --location --request GET '{project-slug}/pipeline' \
--header 'Circle-Token: your_personal_API_token' | jq '.items[] | select(.vcs.tag == "your_tag")'

@yannCI This question is very specifically about API v1, not v2.
CircleCI Server still does not have access to API v2 as far as I’m aware, so API v2 answers are useless to us.

Hi @cos,

This can be done in a similar way with CircleCI API v1:

curl --location --request GET '' \
--header 'Circle-Token: your_personal_API_token'|jq '.[]|select(.vcs_tag == "your_tag")'

Also, you should’ve received an email from us (“Announcing server version 3.0 — what you need to know”) in which we present the features CircleCI server v3.0 will give you access to; among which: pipelines, orbs, API v2.

Please let me know if you haven’t received such an email, and I’ll ask our Marketing team to send it again.

Thanks. I did already know that I could postprocess what the API gives, using jq, but that doesn’t help when the most recent build isn’t even on the list. I ended up having to write a really frustrating loop in shell scripts and python scripts, that repeatedly queries the API for 100 builds at a time, checks whether the tag is in that list, and if not, changes the offset to look at the next 100, and so on. Obviously, this is really really awful, and is a huge gap in your API that needs to have been fixed years ago.

I searched my both work email and the email address I use with this discuss site. I searched for “Announcing server version 3.0” and did not turn up anything at either one. So I do not think you sent me that email, or if you did, the subject line was different.