Keys & usage

200 success

The usage.

As application/json.

organization_idstring (uuid)always present

The organization.

quota_scope"organization"always present

Always organization.

monthstringalways present

The month counted, YYYY-MM (UTC).

apiobjectalways present

API-key data requests.

api.callsintegeralways present

Requests this month.

api.channel"api_key"always present

Always api_key.

api.metered_by"points"always present

Always points: requests have no limit of their own.

csvobjectalways present

CSV exports (the audit-trail download is not one).

csv.exportsintegeralways present

Exports this month.

csv.quotainteger or nullalways present

An export count limit; null (the usual case) when there is none.

csv.metered_by"points" | "exports"always present

points when there is no export count limit, exports when DTG re-armed one.

xlsxobjectalways present

XLSX (as-shown) exports.

xlsx.exportsintegeralways present

Exports this month.

xlsx.quotanullalways present

Always null: XLSX has no count limit.

xlsx.metered_by"points"always present

Always points.

uiobjectalways present

Browser-session data requests.

ui.requestsintegeralways present

Requests this month.

ui.meteredbooleanalways present

Always false: browsing costs no points.

ui.notestringalways present

A sentence saying so.

pointsobjectalways present

The meter that binds.

points.meteredintegeralways present

Points (data values) emitted this month on the API, CSV and XLSX channels, for the caller's credential mode (a sandbox key reads the sandbox total).

points.quotainteger or nullalways present

The organization's monthly points allowance (GET /v2/plans); null when unlimited.

points.channelsarray of stringalways present

Always api, csv, xlsx: the metered channels.

rate_limit_per_minintegeralways present

Requests a minute allowed across the organization.

mauobjectalways present

Monthly active members (ORG_LICENSING 8).

mau.definitionstringalways present

What counts as active, in words.

mau.current_monthintegeralways present

Distinct members active this month so far.

mau.registered_membersintegeralways present

Active memberships now.

mau.rationumber or nullalways present

current_month / registered_members to 3 places; null when there are no members.

mau.historyarray of objectalways present

Earlier months, newest first, at most 12.

mau.history[].monthstringalways present

YYYY-MM.

mau.history[].active_membersintegeralways present

Active members that month.

membersarray of AcctUsageMemberalways present

Every active member, highest points_all first.

members[].membership_idstring (uuid)always present

The membership id.

members[].emailstringalways present

The member's email address.

members[].display_namestring or nullalways present

The member's display name.

members[].seatedbooleanalways present

True when seated.

members[].role"owner" | "admin" | "member"always present

Role.

members[].last_active_atstring (date-time) or nullalways present

The member's most recent successful data request, on any channel (updated at most every 5 minutes).

members[].api_callsintegeralways present

API-key data requests this month.

members[].csv_exportsintegeralways present

CSV exports this month (the audit-trail download excluded).

members[].xlsx_exportsintegeralways present

XLSX (as-shown) exports this month.

members[].ui_requestsintegeralways present

Browser-session data requests this month (unmetered).

members[].points_meteredintegeralways present

Points this member's API, CSV and XLSX requests emitted this month (live and sandbox together).

members[].points_allintegeralways present

Data values emitted on every channel, browsing included (informational; browsing is not metered).

members[].last_request_atstring (date-time) or nullalways present

This member's latest recorded request this month.

401 error

Unauthorized. Codes: key_revoked (the API key was revoked; revoked_at, reason, and a sentence saying when and why); unauthenticated (no API key or session; the key is unknown, or its account, membership or organization is no longer active; the session has expired, passed its 30-day maximum age, or belongs to an unverified email address).

As application/problem+json.

403 error

Forbidden. Codes: no_membership (the account has no active membership in an active organization), account_suspended (O56: the signed-in person's own account is suspended by DTG; reason where recorded), org_suspended (the selected organization is suspended by DTG; the body carries organization {id, name} and reason), org_closed (the selected organization is closed; the body carries organization {id, name}), wrong_instance (a key of the mode this process does not serve: a sandbox key on the live API, or a live key on the sandbox; the body carries expected and base_url, the address that serves it).

As application/problem+json.

404 error

Not Found. Codes: not_found (the X-DTG-Org header is not a uuid, names an organization the caller is not an active member of, or, on an API key, names an organization other than the key's own).

As application/problem+json.

429 error

Only the per-minute rate limit: rate_limited (120 requests a minute per credential, 300 per organization; lower ceilings for a sandbox key), with Retry-After and X-RateLimit-*.

As application/problem+json.

Retry-After header

Seconds to wait before retrying.

X-RateLimit-Limit header

The per-minute request ceiling that applies.

X-RateLimit-Remaining header

Requests left in the current window.

X-RateLimit-Reset header

Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as Retry-After).

200 success

The keys.

As application/json.

api_accessbooleanalways present

True when this member's live keys may read data (the organization holds the API add-on and the member is seated).

api_enabledbooleanalways present

True when an owner or admin has granted this member API access.

api_keys_per_memberintegeralways present

Active live keys a member may hold (2; 0 for an unseated member).

sandbox_keys_per_memberintegeralways present

Active sandbox keys a member may hold (default 2), separate from the live cap.

my_active_keysintegeralways present

The caller's active live keys.

my_active_sandbox_keysintegeralways present

The caller's active sandbox keys.

active_keysintegeralways present

Active live keys in the whole organization.

active_sandbox_keysintegeralways present

Active sandbox keys in the whole organization.

live_base_urlstring (uri)always present

Where a live key is sent, e.g. https://api.datatactical.group. A sandbox key sent there is refused 403 wrong_instance.

sandbox_base_urlstring (uri)always present

Where a sandbox key is sent, e.g. https://api.datatactical.group/sandbox. A live key or a session sent there is refused 403 wrong_instance.

scope"member" | "organization"always present

member (the caller's own keys) or organization (every key, ?all=true).

dataarray of AcctKeyalways present

The keys, newest first.

data[].idstring (uuid)always present

The key id.

data[].namestringalways present

The key's name.

data[].key_prefixstringalways present

The first 16 characters of the key, for recognising it (dtg_live_..., dtg_dev_... or dtg_sandbox_...). Display only.

data[].key_last4string or null

The key's last four characters, as the password-changed mail and notices name it; null for a key minted before T110.

data[].mode"live" | "sandbox"always present

live (real data, every gate) or sandbox (synthetic data only, D68).

data[].created_atstring (date-time)always present

When it was minted.

data[].last_used_atstring (date-time) or nullalways present

When it last authenticated a request; null when never.

data[].revoked_atstring (date-time) or nullalways present

Always null in this list (only active keys are listed).

data[].membership_idstring (uuid)always present

The membership that holds it.

data[].member_emailstringalways present

The holder's email address.

data[].points_monthintegeralways present

Points this key's requests emitted this month (UTC).

data[].calls_monthintegeralways present

Requests made with this key this month (UTC).

401 error

Unauthorized. Codes: key_revoked (the API key was revoked; revoked_at, reason, and a sentence saying when and why); unauthenticated (no API key or session; the key is unknown, or its account, membership or organization is no longer active; the session has expired, passed its 30-day maximum age, or belongs to an unverified email address).

As application/problem+json.

403 error

Forbidden. Codes: no_membership (the account has no active membership in an active organization), account_suspended (O56: the signed-in person's own account is suspended by DTG; reason where recorded), org_suspended (the selected organization is suspended by DTG; the body carries organization {id, name} and reason), org_closed (the selected organization is closed; the body carries organization {id, name}), wrong_instance (a key of the mode this process does not serve: a sandbox key on the live API, or a live key on the sandbox; the body carries expected and base_url, the address that serves it), role_required (the caller's role is not one of those named; the body carries required) with ?all=true from a member.

As application/problem+json.

404 error

Not Found. Codes: not_found (the X-DTG-Org header is not a uuid, names an organization the caller is not an active member of, or, on an API key, names an organization other than the key's own).

As application/problem+json.

429 error

Only the per-minute rate limit: rate_limited (120 requests a minute per credential, 300 per organization; lower ceilings for a sandbox key), with Retry-After and X-RateLimit-*.

As application/problem+json.

Retry-After header

Seconds to wait before retrying.

X-RateLimit-Limit header

The per-minute request ceiling that applies.

X-RateLimit-Remaining header

Requests left in the current window.

X-RateLimit-Reset header

Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as Retry-After).

201 success

The new key, with its secret.

As application/json.

idstring (uuid)always present

The key id.

namestringalways present

The key's name.

mode"live" | "sandbox"always present

The key's mode.

key_prefixstringalways present

The first 16 characters, for recognising it later.

created_atstring (date-time)always present

When it was minted.

keystringalways present

The full key. Send it as Authorization: Bearer <key>. It cannot be shown again.

sandboxtrue

Present (true) only on a sandbox key.

base_urlstring (uri)always present

The address this key is sent to: the live API for a live key, the sandbox API (.../sandbox) for a sandbox key.

notestringalways present

A reminder to store it now; for a sandbox key, that its data is synthetic and must never be published as data.

400 error

Bad Request. Codes: bad_request (mode is not live or sandbox), malformed_json (the body is not valid JSON, or uses an unsupported content encoding).

As application/problem+json.

401 error

Unauthorized. Codes: key_revoked (the API key was revoked; revoked_at, reason, and a sentence saying when and why); unauthenticated (no API key or session; the key is unknown, or its account, membership or organization is no longer active; the session has expired, passed its 30-day maximum age, or belongs to an unverified email address).

As application/problem+json.

403 error

Forbidden. Codes: no_membership (the account has no active membership in an active organization), account_suspended (O56: the signed-in person's own account is suspended by DTG; reason where recorded), org_suspended (the selected organization is suspended by DTG; the body carries organization {id, name} and reason), org_closed (the selected organization is closed; the body carries organization {id, name}), wrong_instance (a key of the mode this process does not serve: a sandbox key on the live API, or a live key on the sandbox; the body carries expected and base_url, the address that serves it), email_unverified (a sandbox key needs a verified email address), key_limit (a cap is reached; the body carries entitlement and active_keys, see AcctKeyLimitProblem), plan_required (live key: the organization has no API add-on, entitlement: api_access; or its payment is past due, entitlement: past_due), api_not_enabled (live key: no owner or admin has granted this member API access). A sandbox key: sandbox_read_only (it may write only clusters).

As application/problem+json.

404 error

Not Found. Codes: not_found (the X-DTG-Org header is not a uuid, names an organization the caller is not an active member of, or, on an API key, names an organization other than the key's own).

As application/problem+json.

413 error

Payload Too Large. Codes: body_too_large (the body is over this endpoint's 4 KB limit; the body carries limit_bytes).

As application/problem+json.

429 error

Only the per-minute rate limit: rate_limited (120 requests a minute per credential, 300 per organization; lower ceilings for a sandbox key), with Retry-After and X-RateLimit-*.

As application/problem+json.

Retry-After header

Seconds to wait before retrying.

X-RateLimit-Limit header

The per-minute request ceiling that applies.

X-RateLimit-Remaining header

Requests left in the current window.

X-RateLimit-Reset header

Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as Retry-After).

204 success

No Content.

401 error

Unauthorized. Codes: key_revoked (the API key was revoked; revoked_at, reason, and a sentence saying when and why); unauthenticated (no API key or session; the key is unknown, or its account, membership or organization is no longer active; the session has expired, passed its 30-day maximum age, or belongs to an unverified email address).

As application/problem+json.

403 error

Forbidden. Codes: no_membership (the account has no active membership in an active organization), account_suspended (O56: the signed-in person's own account is suspended by DTG; reason where recorded), org_suspended (the selected organization is suspended by DTG; the body carries organization {id, name} and reason), org_closed (the selected organization is closed; the body carries organization {id, name}), wrong_instance (a key of the mode this process does not serve: a sandbox key on the live API, or a live key on the sandbox; the body carries expected and base_url, the address that serves it). A sandbox key: sandbox_read_only (it may write only clusters).

As application/problem+json.

404 error

Not Found. Codes: not_found (the X-DTG-Org header is not a uuid, names an organization the caller is not an active member of, or, on an API key, names an organization other than the key's own), not_found also when there is no such active key in this organization that the caller may revoke.

As application/problem+json.

429 error

Only the per-minute rate limit: rate_limited (120 requests a minute per credential, 300 per organization; lower ceilings for a sandbox key), with Retry-After and X-RateLimit-*.

As application/problem+json.

Retry-After header

Seconds to wait before retrying.

X-RateLimit-Limit header

The per-minute request ceiling that applies.

X-RateLimit-Remaining header

Requests left in the current window.

X-RateLimit-Reset header

Seconds until the window refills: on every answer, the time until the bucket is full again; on a refusal, until a request is allowed (as Retry-After).