Measurement Tags

RIPE Atlas measurements can be tagged to help their owners organise and annotate them, and to allow certain actions to be performed on multiple measurements at once. There are two ways of referencing sets of tagged measurements, using a tag or using a label.

A tag is a publicly-visible string that can be applied by one or more users to their measurement(s). Tags are made up of letters, numbers and hyphens and can be used for any purpose. For instance, a set of measurements could be tagged "ipv6-campaign-2018" to indicate the reason for them being started.

A label is a private hexadecimal hash known only to a single user, unless they choose to share it. Labels are individuated in terms of user and tag used, meaning that all measurements created by a specific user and tagged with the same tag will have the same unique label. So for instance, if multiple users have used the tag "ipv6-campaign-2018", they can still refer to their own measurements by label, which could be something like:

afe2f2a763f6394921bb6a2342ae62bce22914c0c80fe1d3da108d823c869e69

Creating measurements with tags

Measurements can be created with tags by following the usual process of measurement creation and specifying a list of tags for each measurement definition.

{ "definitions": [
        {
            "target": "ripe.net",
            "description": "My Tagged Measurement",
            "type": "ping",
            "af": 4,
            "tags": ["my-first-tag"]
        }
    ],
    "probes": [
        {
            "requested": 50,
            "type": "area",
            "value": "WW"
        }
    ]
}

Tagging and detagging existing measurements

An existing measurement can be tagged using its tags endpoint. For example, you can apply the tag my-second-tag to your measurement #4000001 by making a POST request to:

https://atlas.ripe.net/api/v2/measurements/4000001/tags/

with the following JSON content:

{
    "tag": "my-second-tag"
}

The tag can then be removed from the measurement by making a DELETE request to:

https://atlas.ripe.net/api/v2/measurements/400001/tags/my-second-tag/

Finding your private label for a tag

There are two ways to find the label corresponding to a particular tag. One is via the "my-tags" endpoint, which lists all tags and labels that are applied to your measurements:

GET /api/v2/measurements/my-tags/?key=YOUR_KEY_WITH_PERMISSIONS

Note that you will have to replace the key search parameter in the URI with the UUID of a key that has been appointed the right permissions for this operation.

The second way is using the tags endpoint of a measurement that you have tagged, which will show all tags and labels applied to that particular measurement. e.g.:

https://atlas.ripe.net/api/v2/measurements/4000001/tags/

Searching for measurements by tag

The measurement listing can be filtered to only return measurements having particular tags. If multiple tags are specified (separated by commas) then only measurements having all of those tags will be returned.

GET /api/v2/measurements/?tags=my-first-tag,my-second-tag&key=YOUR_KEY_WITH_READ_PERMISSIONS

Note that you will have to replace the key search parameter in the URI with the UUID of a key that has been appointed the right permissions for this operation.

Labels can be used instead of or in combination with tags:

GET /api/v2/measurements/?tags=afe2f2a763f6394921bb6a2342ae62bce22914c0c80fe1d3da108d823c869e69,a-public-tag

Downloading measurement results for a tag

Measurement results can be downloaded for an entire tag in approximate timestamp order from the tag results endpoint:

GET /api/v2/measurements/tags/some-tag-here/results

or only your own measurements:

GET /api/v2/measurements/tags/afe2f2a763f6394921bb6a2342ae62bce22914c0c80fe1d3da108d823c869e69/results?key=YOUR_KEY_WITH_PERMISSIONS

Stopping tagged measurement

A stop request can be created for all of your measurements with a given tag by making an empty POST request to:

https://atlas.ripe.net/api/v2/measurements/my-tags/tag-or-label-here/stop/

Since only your own measurements will be stopped, it doesn't matter if you use the public tag or the private label when stopping measurement tags.