> ## Documentation Index
> Fetch the complete documentation index at: https://docs.byteport.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Location Status
> Inspect a location's refresh state and health.
Return the non-secret refresh state of a location — its lifecycle `status`,
rotation class, access-token expiry, and recent refresh history. Use it to check
on a location after calling
[Refresh](/api-reference/locations/refresh), or to monitor the health of an OAuth
token over time.
Address the location by **`name`** or **`id`**; at least one is required. This is
a `POST` because the target rides in the request body. A non-unique `name`
returns `409` with the candidates — resend with the `id` of the one you want.
```bash cURL theme={null}
curl -X POST https://api.byteport.com/v1/locations/status \
-H "Authorization: Bearer $BYTEPORT_API_KEY" \
-H "User-Agent: my-app/1.0" \
-H "Content-Type: application/json" \
-d '{ "name": "marketing-assets" }'
```
```javascript JavaScript theme={null}
const res = await fetch("https://api.byteport.com/v1/locations/status", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.BYTEPORT_API_KEY}`,
"User-Agent": "my-app/1.0",
"Content-Type": "application/json",
},
body: JSON.stringify({ name: "marketing-assets" }), // or { id: "..." }
});
const status = await res.json();
```
```python Python theme={null}
import os, requests
status = requests.post(
"https://api.byteport.com/v1/locations/status",
headers={
"Authorization": f"Bearer {os.environ['BYTEPORT_API_KEY']}",
"User-Agent": "my-app/1.0",
},
json={"name": "marketing-assets"}, # or {"id": "..."}
).json()
```
```json 200 OK theme={null}
{
"status": "active",
"rotation_class": "oauth-stable",
"access_token_expires_at": "2026-07-07T18:30:00Z",
"refresh_requested": false,
"consecutive_refresh_failures": 0,
"last_refresh_attempt_at": "2026-07-06T02:11:04Z"
}
```
```json 404 Not Found theme={null}
{
"error": 404,
"message": "no location named marketing-assets"
}
```
## OpenAPI
````yaml POST /v1/locations/status
openapi: 3.1.0
info:
title: Byteport API
description: >-
The Byteport API lets you move, share, and manage files across every storage
location connected to your workspace through a single HTTP interface.
version: 1.0.0
servers:
- url: https://api.byteport.com
security:
- bearerAuth: []
paths:
/v1/locations/status:
post:
summary: Get Location Status
description: >-
Return the non-secret refresh state of a location — lifecycle status,
rotation class, token expiry, and recent refresh history — addressed by
`name` or `id`. A `POST` because the target rides in the request body.
requestBody:
required: true
content:
application/json:
schema:
type: object
description: Address the location by `name` or `id`.
properties:
name:
type: string
description: >-
The location name (its `label`). Resolved to a single
location; if the name matches several, also send `id` to
pick one.
example: prod-backups
id:
type: string
description: >-
The location's UUID. Addresses one location directly, or —
alongside `name` — selects which match of a non-unique name
to act on.
example: 3f9a2b7c-1d4e-4a8f-9c2b-6e5d0a1f7b83
responses:
'200':
description: The location's refresh status.
content:
application/json:
schema:
$ref: '#/components/schemas/RefreshStatus'
'400':
$ref: '#/components/responses/Error'
'401':
$ref: '#/components/responses/Error'
'404':
$ref: '#/components/responses/Error'
'409':
description: The `name` matches more than one location; resend with an `id`.
content:
application/json:
schema:
$ref: '#/components/schemas/LocationConflict'
components:
schemas:
RefreshStatus:
type: object
description: >-
The non-secret refresh state of a credential, returned by the Status
endpoints.
properties:
status:
type: string
description: Lifecycle state of the credential.
enum:
- active
- failed
- needs_attention
example: active
validation_error:
type: string
description: >-
Provider-side reason the credential was marked failed. Omitted when
active.
example: invalid_grant
rotation_class:
type: string
description: >-
How the credential's secret rotates. Populated for OAuth providers
(`oauth-stable`, `oauth-single-use`); omitted for static credentials
that don't rotate.
example: oauth-stable
access_token_expires_at:
type: string
format: date-time
description: >-
For OAuth providers, when the cached access token expires (RFC
3339). Omitted for providers without expiring access tokens.
example: '2026-07-07T18:30:00Z'
refresh_requested:
type: boolean
description: >-
Whether a refresh is currently queued for this credential (set by
the Refresh endpoint, cleared once the refresher runs).
example: false
consecutive_refresh_failures:
type: integer
description: >-
Count of back-to-back failed refresh attempts. Resets to 0 on a
successful refresh.
example: 0
last_refresh_attempt_at:
type: string
format: date-time
description: >-
When the refresher last attempted this credential (RFC 3339).
Omitted if never attempted.
example: '2026-07-06T02:11:04Z'
last_refresh_error:
type: string
description: >-
Error from the most recent refresh attempt. Omitted when the last
attempt succeeded or none has run.
example: temporary network error
LocationConflict:
type: object
description: >-
Returned with `409` by a single-location endpoint when the `name` in the
body matches more than one location. Re-issue the request with an `id`
field set to one of the candidates.
properties:
error:
type: string
description: Human-readable explanation of the ambiguity.
example: >-
name is not unique; re-issue with an "id" field for one of the
candidates
name:
type: string
description: The ambiguous location name from the request body.
example: prod-backups
candidates:
type: array
description: >-
Every location that carries this name. Choose one and resend with
its `id`.
items:
$ref: '#/components/schemas/LocationRef'
Error:
type: object
required:
- error
- message
properties:
error:
type: integer
message:
type: string
LocationRef:
type: object
description: >-
A credential addressed by its label ("location name"). Because labels
are not unique, a single name can resolve to several of these.
`provider` and the timestamps let you tell same-named credentials apart
and pick the `id` to act on.
properties:
id:
type: string
description: >-
The credential's UUID. Pass it back as the `?id=` query parameter to
disambiguate a non-unique name on the mutating Locations endpoints.
example: 3f9a2b7c-1d4e-4a8f-9c2b-6e5d0a1f7b83
provider:
type: string
description: The storage backend this credential authenticates against.
example: s3
created_at:
type: string
format: date-time
description: When the credential was created (RFC 3339, UTC).
example: '2026-05-14T17:02:11Z'
updated_at:
type: string
format: date-time
description: When the credential was last modified (RFC 3339, UTC).
example: '2026-06-01T09:44:20Z'
responses:
Error:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````