# The `probes` Array in Detail

The probes array contains single objects.

# A Single `probes` Object

Basically, there are six types of requests: area, country, prefix, asn, probes and msm. In each case, you'll be stating how many probes of that type you'd like to use (requested) and what subsection of that type you're looking at (value). In addition, you can opt to further restrict each request using probe tags. We'll go over the request types one by one.

# Area

For our purposes, the world is broken up into five arbitrary geographical areas:

WW (Worldwide)
West
North-Central
South-Central
North-East
South-East

# Country

If you want to request probes by country, specify the ISO two-letter country code here. For example, you would use CA for Canada, NL for the Netherlands, and KR for South Korea.

# Prefix

This is an IP prefix. For example:

"probes": [
    {
        "requested": 5,
        "type": "prefix",
        "value": "193.3.6.0/8"
    }
]

# ASN

For ASNs, just the number is sufficient. For example:

"probes": [
    {
        "requested": 5,
        "type": "asn",
        "value": 3333
    }
]

# Probes

Probes can be explicitly requested by requesting type: "probe" and specifying a comma-separated list of integers as the value:

"probes": [
    {
        "requested": 3,
        "type": "probes",
        "value": "1,2,3"
    }
]

# Measurement (`msm`)

Finally, if you want to use the same probes as in a past measurement, you can simply specify the previous measurement ID in the value field:

"probes": [
    {
        "requested": 1,
        "type": "msm",
        "value": 1000002
    }
]

# Probe Tags

Any of the above request types can be further restricted based on probe tags. This is achieved by specifying an optional tags_include and/ortags_exclude field which can contain a comma-separated list of probe tags. They serve to further constrain the probe collection by respectively including or excluding probes that have the specified tags attached.

For example, to request 10 probes from anywhere in the world that are in a data centre, and do have working IPv4 but do not have working IPv6:

"probes": [
    {
        "requested": 10,
        "type": "area",
        "value": "WW"
        "tags": {
            "include": ["datacentre", "system-ipv4-works"],
            "exclude": ["system-ipv6-works"]
        }
    }
]

Caution The old syntax for setting the tags, using a tags sub-object, that featured the fields include and exclude, is still recognised. This syntax is deprecated and will be removed in the next major version of the API.

# The `probes` and `participation request` Objects

The probes array will be turned into a participation request object by RIPE Atlas after the measurement has been created. It will also have its own ID and URL where you can view it. You can read more about the participation object here.

# Combining requests

Each of the past examples have shown the probes array containing only one kind of request. However, the probes array can contain multiple probe requests of multiple types. You can combine them as you wish in order to fulfil your requirements, and the API will schedule measurements for all of them. The following example shows a probes array specifying probes from an ASN and probes from an area.

"probes": [
    {
        "requested": 5,
        "type": "asn",
        "value": 3333
    },
    {
        "requested": 10,
        "type": "area",
        "value": "WW"
    }
]

# Validating complex `probes` array

In case the probes array holds mutliple items, as in the Combining requests example, the API will validate all of the items and proceed with the ones that are valid. The API will attach warning objects for those invalid probes items inside its response.

Imagine someone requesting measurements from two different areas; e.g. from anywhere in the world (WW) and from Mars. In this case, the API will fulfil the requested measurements from WW, but not those from Mars. Therefore, the API response will hold information corresponding to the ones from WW (success), and additionally attach a warning corresponding to the ones from Mars (failure).

Warnings will be attached whenever there is a probes array that has a mix of invalid and valid items. In case all the items are invalid, then the API will send out an error message. Validation may fail for two main reasons:

The specified request is invalid per se, probably due to an error in the type or value specified. Look at the above A Single probes object section for more detail.
There are no probes in the specified request. For example ASNs which are not yet covered by the Atlas platform.

Warnings will also appear when creating a participation request with an array having valid and invalid items.

← The probes Array Fields for all Definitions →

# The probes Array in Detail

# A Single probes Object