# Regions

The regions a workspace's data can live in, with the addresses its data is sent to and queried at.

Contains: [Credential](https://sparklogs.com/docs/api/reference/credential.md)

Ids: text.

- `GET /regions` [List regions](#list-regions)

## Region object

A region is a place a workspace's data can live, with the addresses its data is sent to and queried at.

- `id` (string): The region's id.
- `name` (string): The region's name.
- `sort_order` (integer): Where the region sorts in a list of regions.
- `ingest_uri` (string): The address agents send this region's log data to.
- `query_uri` (string): The address this region's data is queried at.
- `bigquery_location` (string or null): The BigQuery location this region's workspace datasets are created in, such as `US`. list-regions returns it only when named in `fields`; a workspace's region always carries it.

## List regions

`GET https://engine.sparklogs.app/app-api/regions`

Preview

Returns every region a workspace's data can live in, in sort order, with the addresses its data is sent to and queried at.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token

Needs no privilege: every caller gets the same list of regions.

### Behavior

- Retry: Safe to send again

### Query parameters

- `fields` (array of string): Comma-separated top-level fields of each object to return instead of the default set.

Sent by default: `id`, `name`, `sort_order`, `ingest_uri`, `query_uri`

Sent only when named in `fields`: `bigquery_location`

### Response (200)

- `regions` (array of Region, required): Every one of the regions you can see.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A query parameter it does not take, one given twice, or `fields` naming a field it does not have. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Example

List the regions

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/regions" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "regions retrieved",
  "regions": [
    {
      "id": "us-central",
      "name": "United States",
      "sort_order": 1,
      "ingest_uri": "https://ingest-usc1.engine.sparklogs.app",
      "query_uri": "https://query-usc1.engine.sparklogs.app"
    }
  ]
}
```

---

Source: <https://sparklogs.com/docs/api/reference/regions>
All SparkLogs documentation in Markdown: <https://sparklogs.com/llms.txt>
