Skip to content

Create a Trails delivery

Delivers the organization's Trails events, from now on, into the Observability dataset of a project and environment, as logs. Also needs obs.logs.ingest on the project (403 access_denied naming it). 400 when the project isn't a live project of the organization or the environment isn't valid; 409 quota_exceeded (an allocation quota: with quota, its limit and used, never Retry-After) at 5 deliveries. With an Idempotency-Key, retrying the same request within 24 hours answers the first 201 again, with Idempotent-Replayed: true; the same key with a different request is 409 idempotency_conflict.

POST
https://trails.ezghcloud.com/v1/organizations/{orgId}/deliveries

Authorization

  • apiKeyoptionalHTTP
  • oauthoptionalHTTP
  • sessionCookieoptionalAPI key in cookie

Path parameters

  • orgIdstringrequired

    The organization's ID or slug (org_…).

Header parameters

  • Idempotency-Keyoptionalstring | null

    1 to 200 printable ASCII characters, scoped to the organization and kept 24 hours.

Request bodyJSONrequired

  • environmentstringrequired

    The destination dataset's environment, e.g. production: trimmed and lowercased, then 1 to 63 of a-z, 0-9, '.', '_' and '-', starting with a letter or digit.

  • namestringrequired

    1 to 100 characters.

  • projectIdstringrequired

    A live project of the organization.

    format: uuid
  • enabledoptionalboolean | null

    Default true.

  • includeReadsoptionalboolean | null

    Default false.

Returns

201

Created.

JSON
  • createdAtstringrequired
    format: date-time
  • droppedEventsintegerrequired

    Events never delivered: records Observability rejected, and events older than the 3-day backlog.

    format: int64
  • enabledbooleanrequired

    false pauses delivery without deleting it.

  • environmentstringrequired

    The destination dataset's environment, normalized (lowercase). Can't be changed.

  • idstringrequired
    format: uuid
  • includeReadsbooleanrequired

    Whether read-only API calls are delivered too (billed as Observability log ingest in the project).

  • namestringrequired

    1 to 100 characters.

  • organizationIdstringrequired
    format: uuid
  • projectIdstringrequired

    The destination project. Can't be changed.

    format: uuid
  • regionstringrequired
  • resourceNamestringrequired

    ezgh::org_…:tdl_…

  • slugstringrequired

    tdl_ and 12 characters.

  • statusstringrequired

    paused when not enabled; failing when the last attempt failed after the last success; else active.

  • updatedAtstringrequired
    format: date-time
  • lastDeliveredAtoptionalstring | null
    format: date-time
  • lastErroroptionalstring | null

    Why the last attempt failed, for people.

  • lastErrorAtoptionalstring | null
    format: date-time

400

invalid_request, invalid_cursor, invalid_query (with line and column), or lookup_too_broad.

JSON
  • errorobjectrequired
    6 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • columnoptionalinteger

      invalid_query: where the SQL went wrong.

    • lineoptionalinteger

      invalid_query: where the SQL went wrong.

    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Trails Query's are audit.queries.queriesPerHour and audit.queries.bytesReadPerHour, rate quotas with a PT1H window; Trails deliveries' is audit.deliveries.perOrganization, an allocation quota of 5 (409, with used). Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

    • reasonoptionalstring

      query_failed: the query's own error code.

401

unauthenticated: no credential, or one that doesn't check out.

JSON
  • errorobjectrequired
    6 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • columnoptionalinteger

      invalid_query: where the SQL went wrong.

    • lineoptionalinteger

      invalid_query: where the SQL went wrong.

    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Trails Query's are audit.queries.queriesPerHour and audit.queries.bytesReadPerHour, rate quotas with a PT1H window; Trails deliveries' is audit.deliveries.perOrganization, an allocation quota of 5 (409, with used). Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

    • reasonoptionalstring

      query_failed: the query's own error code.

403

access_denied: the caller's policies don't allow the action; forbidden_origin: a cookie-authenticated write from an origin that isn't allowed.

JSON
  • errorobjectrequired
    6 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • columnoptionalinteger

      invalid_query: where the SQL went wrong.

    • lineoptionalinteger

      invalid_query: where the SQL went wrong.

    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Trails Query's are audit.queries.queriesPerHour and audit.queries.bytesReadPerHour, rate quotas with a PT1H window; Trails deliveries' is audit.deliveries.perOrganization, an allocation quota of 5 (409, with used). Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

    • reasonoptionalstring

      query_failed: the query's own error code.

404

not_found: unknown, malformed, or in an organization the caller isn't in.

JSON
  • errorobjectrequired
    6 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • columnoptionalinteger

      invalid_query: where the SQL went wrong.

    • lineoptionalinteger

      invalid_query: where the SQL went wrong.

    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Trails Query's are audit.queries.queriesPerHour and audit.queries.bytesReadPerHour, rate quotas with a PT1H window; Trails deliveries' is audit.deliveries.perOrganization, an allocation quota of 5 (409, with used). Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

    • reasonoptionalstring

      query_failed: the query's own error code.

409

query_not_finished (with Retry-After), query_failed (with reason), query_cancelled, query_finished, idempotency_conflict, idempotency_in_progress (with Retry-After), organization_deletion_pending, conflict (the resource changed meanwhile; nothing was changed), or quota_exceeded for an allocation quota (with quota, never Retry-After).

JSON
  • errorobjectrequired
    6 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • columnoptionalinteger

      invalid_query: where the SQL went wrong.

    • lineoptionalinteger

      invalid_query: where the SQL went wrong.

    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Trails Query's are audit.queries.queriesPerHour and audit.queries.bytesReadPerHour, rate quotas with a PT1H window; Trails deliveries' is audit.deliveries.perOrganization, an allocation quota of 5 (409, with used). Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

    • reasonoptionalstring

      query_failed: the query's own error code.

413

payload_too_large: the body is over 1 MiB.

JSON
  • errorobjectrequired
    6 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • columnoptionalinteger

      invalid_query: where the SQL went wrong.

    • lineoptionalinteger

      invalid_query: where the SQL went wrong.

    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Trails Query's are audit.queries.queriesPerHour and audit.queries.bytesReadPerHour, rate quotas with a PT1H window; Trails deliveries' is audit.deliveries.perOrganization, an allocation quota of 5 (409, with used). Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

    • reasonoptionalstring

      query_failed: the query's own error code.

429

too_many_requests or too_many_queries, with Retry-After; or quota_exceeded for a rate quota (with quota), never with Retry-After.

JSON
  • errorobjectrequired
    6 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • columnoptionalinteger

      invalid_query: where the SQL went wrong.

    • lineoptionalinteger

      invalid_query: where the SQL went wrong.

    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Trails Query's are audit.queries.queriesPerHour and audit.queries.bytesReadPerHour, rate quotas with a PT1H window; Trails deliveries' is audit.deliveries.perOrganization, an allocation quota of 5 (409, with used). Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

    • reasonoptionalstring

      query_failed: the query's own error code.

500

internal_error: a bug; the details are in the logs, under the request ID.

JSON
  • errorobjectrequired
    6 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • columnoptionalinteger

      invalid_query: where the SQL went wrong.

    • lineoptionalinteger

      invalid_query: where the SQL went wrong.

    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Trails Query's are audit.queries.queriesPerHour and audit.queries.bytesReadPerHour, rate quotas with a PT1H window; Trails deliveries' is audit.deliveries.perOrganization, an allocation quota of 5 (409, with used). Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

    • reasonoptionalstring

      query_failed: the query's own error code.

503

unavailable: a dependency the request needs is down. Retry after Retry-After.

JSON
  • errorobjectrequired
    6 properties
    • codestringrequired
      maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
    • messagestringrequired
      maxLength: 1024
    • columnoptionalinteger

      invalid_query: where the SQL went wrong.

    • lineoptionalinteger

      invalid_query: where the SQL went wrong.

    • quotaoptionalobject

      quota_exceeded: the quota that refused the request. Trails Query's are audit.queries.queriesPerHour and audit.queries.bytesReadPerHour, rate quotas with a PT1H window; Trails deliveries' is audit.deliveries.perOrganization, an allocation quota of 5 (409, with used). Never with Retry-After.

      11 properties
      • idstringrequired
      • kindallocationorrateorusageorconcurrencyrequired
      • limitintegerrequired
        minimum: 0
      • scopeorganizationorprojectorresourcerequired
      • inFlightoptionalinteger
        minimum: 0
      • periodStartoptionalstring
        format: date-time
      • regionoptionalstring
      • resetsAtoptionalstring
        format: date-time
      • scopeResourceNameoptionalstring
      • usedoptionalinteger
        minimum: 0
      • windowoptionalstring

        rate only: an ISO 8601 duration, PT1S to PT1H.

    • reasonoptionalstring

      query_failed: the query's own error code.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close