Private Sets

Private Sets enable users to put together arbitrary groupings of Ethereum validators, and to easily track aggregated statistics of these persistent clusters.

Private sets endpoints are available to Build [4 sets], Growth [10 sets] and Enterprise plans on the Rated API. Head on over to Plans to learn more.

Introducing Private Sets

Private sets empower organizations to implement sophisticated monitoring strategies, including A/B testing, performance benchmarking, and multivariate analysis.

By organizing validators into private sets, orgs can execute controlled experiments and analyses to assess various aspects of their validators' performance. This strategic grouping not only enhances the understanding of individual and collective validator efficiency but also informs decisions aimed at optimizing overall performance.

Head to our Private Sets guide to get a detailed walk through on how to create and manage tags and call the sets performance and rewards endpoints.

Get all tags

This endpoint returns all the tags that are associated with your organization.

GET/v1/tags

Query parameters

Response

200400

Successful Response

Body

application/json

previousPrevious

nextNext

pages*Pages

results*Results

Request

JavaScriptCurlPythonHTTP

const response = await fetch('/v1/tags', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400

{
  "previous": "https://endpoint?limit=10&offset=10",
  "next": "https://endpoint?limit=10&offset=10",
  "pages": 10,
  "results": [
    {
      "id": "96cbc789-5a03-4110-abeb-67f5d4f65323",
      "name": "us-west-1",
      "network": "holesky",
      "organizationId": "d03841a7-d830-47a2-9f96-3f2ddf7d9b43",
      "createdBy": "467c1246-be63-40c2-82c3-10f80d3238bb",
      "createdAt": "2024-03-31T18:13:27.584133"
    }
  ]
}

---

Create a new tag

To call a private set's effectiveness, you must first create a tag which acts as a unique identifier for the set. This endpoint allows you to create a new tag. You must give your tag a name. The response will contain the tag id which you will then use to add validators using the add validator endpoint.

POST/v1/tags

Header parameters

Body

application/json

name*Name

Response

201400

Successful Response

Body

application/json

id*Id

name*Name

network*Network

An enumeration.

mainnetholesky

organizationId*Organizationid

createdBy*Createdby

createdAt*Createdat

updatedAtUpdatedat

Request

JavaScriptCurlPythonHTTP

const response = await fetch('/v1/tags', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "us-west-1"
    }),
});
const data = await response.json();

Response

201400

{
  "id": "96cbc789-5a03-4110-abeb-67f5d4f65323",
  "name": "us-west-1",
  "network": "holesky",
  "organizationId": "d03841a7-d830-47a2-9f96-3f2ddf7d9b43",
  "createdBy": "467c1246-be63-40c2-82c3-10f80d3238bb",
  "createdAt": "2024-03-31T18:13:27.584133"
}

Build tier orgs can create upto 4 tags while Growth tier orgs can create upto 20 tags.

---

Get details about a tag

This endpoint will return the details on a tag including its name, id and when it was created.

GET/v1/tags/{id}

Path parameters

id*Id

Header parameters

Response

200400

Successful Response

Body

application/json

id*Id

name*Name

network*Network

An enumeration.

mainnetholesky

organizationId*Organizationid

createdBy*Createdby

createdAt*Createdat

updatedAtUpdatedat

Request

JavaScriptCurlPythonHTTP

const response = await fetch('/v1/tags/{id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400

{
  "id": "96cbc789-5a03-4110-abeb-67f5d4f65323",
  "name": "us-west-1",
  "network": "holesky",
  "organizationId": "d03841a7-d830-47a2-9f96-3f2ddf7d9b43",
  "createdBy": "467c1246-be63-40c2-82c3-10f80d3238bb",
  "createdAt": "2024-03-31T18:13:27.584133"
}

---

Update a tag

This endpoint allows you to update the name associated with your tag.

PATCH/v1/tags/{id}

Path parameters

id*Id

Header parameters

Body

application/json

name*Name

Response

200400422

Successful Response

Body

application/json

id*Id

name*Name

network*Network

An enumeration.

mainnetholesky

organizationId*Organizationid

createdBy*Createdby

createdAt*Createdat

updatedAtUpdatedat

Request

JavaScriptCurlPythonHTTP

const response = await fetch('/v1/tags/{id}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "name": "us-west-2"
    }),
});
const data = await response.json();

Response

200400422

{
  "id": "96cbc789-5a03-4110-abeb-67f5d4f65323",
  "name": "us-west-1",
  "network": "holesky",
  "organizationId": "d03841a7-d830-47a2-9f96-3f2ddf7d9b43",
  "createdBy": "467c1246-be63-40c2-82c3-10f80d3238bb",
  "createdAt": "2024-03-31T18:13:27.584133"
}

---

Get all validators in a tag

This endpoint allows you to get all the validators associated with a tag. It returns a paginated list of pubkeys along with their metadata.

GET/v1/tags/{id}/validators

Path parameters

id*Id

Query parameters

Header parameters

Response

200400

Successful Response

Body

application/json

previousPrevious

nextNext

pages*Pages

results*Results

Request

JavaScriptCurlPythonHTTP

const response = await fetch('/v1/tags/{id}/validators', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200400

{
  "previous": "https://endpoint?limit=10&offset=10",
  "next": "https://endpoint?limit=10&offset=10",
  "pages": 10,
  "results": [
    {
      "validatorPubkey": "0x800...",
      "tagId": "96cbc789-5a03-4110-abeb-67f5d4f65323",
      "tagName": "us-west-1",
      "createdBy": "d03841a7-d830-47a2-9f96-3f2ddf7d9b43",
      "createdAt": "2024-03-31T18:13:27.584133"
    }
  ]
}

---

Add validators to a tag

This endpoint allows you to add validators to a tag. You must pass an array of validator pubkeys in the body.

POST/v1/tags/{id}/validators

Path parameters

id*Id

Header parameters

Body

application/json

pubkeys*Pubkeys

Response

201400

Successful Response

Body

application/json

validatorPubkey*Validatorpubkey

tagId*Tagid

tagName*Tagname

createdBy*Createdby

createdAt*Createdat

Request

JavaScriptCurlPythonHTTP

const response = await fetch('/v1/tags/{id}/validators', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "pubkeys": [
        "0x00..",
        "0x01..."
      ]
    }),
});
const data = await response.json();

Response

201400

[
  {
    "validatorPubkey": "0x800...",
    "tagId": "96cbc789-5a03-4110-abeb-67f5d4f65323",
    "tagName": "us-west-1",
    "createdBy": "d03841a7-d830-47a2-9f96-3f2ddf7d9b43",
    "createdAt": "2024-03-31T18:13:27.584133"
  }
]

You can add upto 1,000 validators at a time with an upper bound of 15,000 validators per tag. If you'd like to add more than that per tag, please reach out to us at [e-mail]!

---

Remove validator pubkey from a tag

This endpoint allows you to remove a validator from a tag by passing the validator pubkey as a path parameter.

DELETE/v1/tags/{id}/validators/{pubkey}

Path parameters

id*Id

pubkey*Pubkey

Header parameters

Response

204400

Successful Response

Request

JavaScriptCurlPythonHTTP

const response = await fetch('/v1/tags/{id}/validators/{pubkey}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

Response

400

{
  "detail": [
    {
      "loc": [
        "text"
      ],
      "msg": "text",
      "type": "text"
    }
  ]
}

Note that removing a validator key from a tag has the same impact on the historical performance of the private set as exiting your key from a cluster would ie, the exited key still impacts the historical view of the set's perfomance.

---

As a reminder, note that this page only walks you through the creation and management of your tags, which is a precursor to calling the set's performance and rewards endpoints. You can find the effectiveness endpoint for sets here, and rewards endpoint for sets here or head to our Private Sets user guide!