Ingest Keys

Model

Fields

Field

Type

Description
object
"ingest_key"
id
string Unique identifier, prefixed with ik_.
source_id
string The source this key writes into.
source_name
string | null
url
string | null The Tailglow-issued address to send records to, ready to use. POST your payload to it and append &collection=<name> to choose where the records land; a collection is created the first time data arrives for it. Lasts as long as the project does. Null until the project has a provisioned server, which is the only window in which no address reaches it.
custom_urls
string[] The same source reached through the team's verified custom ingest domains, one entry each, every one carrying the key exactly as url does. Empty when none are configured. Prefer these for browser traffic, where a first-party host survives the blockers that reject a shared analytics domain. An entry disappears if its domain is removed or stops resolving.
key
string The credential embedded in url. Publishable, in the sense that it belongs in client-side code the way an analytics site tag does. It permits writing records into this source and nothing else: it cannot read, and it carries no access to anything outside this source.
status
Whether records sent to this URL are still accepted.
created_at
last_used_at
| null When data was last received at this URL; null if it has never been used.

List Ingest Keys

Endpoint

Retrieve every address that can send records to a source.

ingest_keys:read
GET
/v1/projects/:project_id/sources/:source_id/ingest_keys

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.
source_id
string Unique identifier of the source.

Query Parameters

Field

Type

Description
order_by
string Field used to order the ingest keys. Defaults to "created_at". Accepted values: "created_at","status".
status
Filter by whether the URL still accepts records.
project_id
string Filter to URLs whose source belongs to a project.
source_id
string Filter to URLs belonging to a single source.
limit
number Maximum number of items to return. Defaults to 25. Minimum: 1. Maximum: 200.
after
string Cursor from pagination.next_cursor of a previous response. Returns the resources after that page.
before
string Cursor from pagination.prev_cursor of a previous response. Returns the resources before that page.
sort
string Sort direction for the result set. Defaults to "desc". Accepted values: "asc","desc".

Comments

  • after and before are mutually exclusive.

Response

200 
{
  message: string;
  data: IngestKey[];
  status: 200;
  error: null;
  pagination: Pagination;
  endpoint: string;
}

Retrieve Ingest Key

Endpoint

Retrieve a single ingest key.

ingest_keys:read
GET
/v1/projects/:project_id/sources/:source_id/ingest_keys/:ingest_key_id

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.
source_id
string Unique identifier of the source.
ingest_key_id
string Unique identifier of the ingest key.

Response

200 
{
  message: string;
  data: IngestKey;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Create Ingest Key

Endpoint

Create an ingest key for a source. Use this to rotate: create the replacement, deploy it, then delete the old one.

ingest_keys:write
POST
/v1/projects/:project_id/sources/:source_id/ingest_keys

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.
source_id
string Unique identifier of the source.

Request Body

Field

Type

Requirement

Description
source_id
string
Optional
Source the URL writes into. Ignored when the nested path supplies it.

Comments

  • The source is supplied by the path.
  • The source has to belong to your team.
  • The full key is returned on create and never again. Store it when you receive it.

Response

201 
{
  message: string;
  data: IngestKey;
  status: 201;
  error: null;
  pagination: null;
  endpoint: string;
}

Delete Ingest Key

Endpoint

Delete an ingest key. Records already sent to it are unaffected; the address stops being accepted.

ingest_keys:delete
DELETE
/v1/projects/:project_id/sources/:source_id/ingest_keys/:ingest_key_id

Path Parameters

Field

Type

Description
project_id
string Unique identifier of the project.
source_id
string Unique identifier of the source.
ingest_key_id
string Unique identifier of the ingest key.

Comments

  • Deletion is immediate. Anything still sending with this key starts failing straight away.

Response

200 
{
  message: string;
  data: null;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Referenced Types

ISODateString

An ISO 8601 date-time string returned at the JSON API boundary.

IngestKeyStatus

active
revoked
disabled