telnesstech
View as MarkdownOpen in ClaudeOpen in ChatGPT

Reports

Retrieve generated reports and download their files.

List reports

GET/reports

List platform-generated report runs for a given report key, newest first.

Only report runs created within the last 30 days are returned.

Query parameters

reportKeystringrequired

The key identifying the report to list runs for.

limitinteger>= 1<= 1000default 100

The maximum number of items to return.

cursorstring

Opaque pagination token from a previous response's nextCursor.

Responses

200

A list of report runs.

application/json

A list of report runs.

object

itemsarray of ReportRunrequired
Show child attributes
reportRunIdstringuuidrequired

The unique identifier for this report run.

reportKeystringrequired

Identifies which report was generated.

statusenum<string>required

The current stage of a report run in its lifecycle.

values

  • QUEUED
  • RUNNING
  • SUCCEEDED
  • FAILED
downloadUrlstring | nullurirequired

A time-limited link to download the generated file. Present only once the report has succeeded; null while it is still generating or if it failed.

createdAtstringdate-timerequired

When the report run was requested.

completedAtstring | nulldate-timerequired

When the report run finished generating. Null while it is still in progress.

paginationobjectrequired

Cursor-based pagination information returned by list endpoints. Pass nextCursor as the cursor query parameter of the next request to fetch the following page.

Show child attributes
nextCursorstring | nullrequired

Opaque token for fetching the next page. Null when no more results.

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. It is the code the failing system answered with — one of ours where the endpoint publishes one, an operator's own code where the failure came from an operator, and otherwise the request status. Prefer internalCode for branching.

internalCodestring

Names the condition that failed, from our own registry, independently of which system reported it and of the HTTP status. Stable across releases and the code to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. It is the code the failing system answered with — one of ours where the endpoint publishes one, an operator's own code where the failure came from an operator, and otherwise the request status. Prefer internalCode for branching.

internalCodestring

Names the condition that failed, from our own registry, independently of which system reported it and of the HTTP status. Stable across releases and the code to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. It is the code the failing system answered with — one of ours where the endpoint publishes one, an operator's own code where the failure came from an operator, and otherwise the request status. Prefer internalCode for branching.

internalCodestring

Names the condition that failed, from our own registry, independently of which system reported it and of the HTTP status. Stable across releases and the code to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. It is the code the failing system answered with — one of ours where the endpoint publishes one, an operator's own code where the failure came from an operator, and otherwise the request status. Prefer internalCode for branching.

internalCodestring

Names the condition that failed, from our own registry, independently of which system reported it and of the HTTP status. Stable across releases and the code to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

  • X-Api-Key
  • Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

GET /reports
curl 'https://apiv2.example.com/api/v2/reports?reportKey=REPORT_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'
fetch('https://apiv2.example.com/api/v2/reports?reportKey=REPORT_KEY', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})
requests.get("https://apiv2.example.com/api/v2/reports",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    },
    params={
      "reportKey": "REPORT_KEY"
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/reports?reportKey=REPORT_KEY"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "items": [
    {
      "reportRunId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "reportKey": "subscriber_base_and_revenue",
      "status": "SUCCEEDED",
      "downloadUrl": "https://example-bucket.s3.amazonaws.com/reports/f47ac10b.csv?X-Amz-Signature=...",
      "createdAt": "2024-01-10T08:00:00Z",
      "completedAt": "2024-01-10T08:02:31Z"
    }
  ],
  "pagination": {
    "nextCursor": null
  }
}
{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}
{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}
{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}
{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Get report

GET/reports/{reportRunId}

Retrieve a generated report by its identifier. Once the report has finished generating, the response includes a time-limited link to download the file directly.

Path parameters

reportRunIdstringuuidrequired

The identifier of the report run.

Responses

200

A report run object.

application/json

A report run object.

objectReportRun

A generated report and its current state. When the report has finished generating, a time-limited download link is provided so the file can be fetched directly.

reportRunIdstringuuidrequired

The unique identifier for this report run.

reportKeystringrequired

Identifies which report was generated.

statusenum<string>required

The current stage of a report run in its lifecycle.

values

  • QUEUED
  • RUNNING
  • SUCCEEDED
  • FAILED
downloadUrlstring | nullurirequired

A time-limited link to download the generated file. Present only once the report has succeeded; null while it is still generating or if it failed.

createdAtstringdate-timerequired

When the report run was requested.

completedAtstring | nulldate-timerequired

When the report run finished generating. Null while it is still in progress.

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. It is the code the failing system answered with — one of ours where the endpoint publishes one, an operator's own code where the failure came from an operator, and otherwise the request status. Prefer internalCode for branching.

internalCodestring

Names the condition that failed, from our own registry, independently of which system reported it and of the HTTP status. Stable across releases and the code to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. It is the code the failing system answered with — one of ours where the endpoint publishes one, an operator's own code where the failure came from an operator, and otherwise the request status. Prefer internalCode for branching.

internalCodestring

Names the condition that failed, from our own registry, independently of which system reported it and of the HTTP status. Stable across releases and the code to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. It is the code the failing system answered with — one of ours where the endpoint publishes one, an operator's own code where the failure came from an operator, and otherwise the request status. Prefer internalCode for branching.

internalCodestring

Names the condition that failed, from our own registry, independently of which system reported it and of the HTTP status. Stable across releases and the code to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. It is the code the failing system answered with — one of ours where the endpoint publishes one, an operator's own code where the failure came from an operator, and otherwise the request status. Prefer internalCode for branching.

internalCodestring

Names the condition that failed, from our own registry, independently of which system reported it and of the HTTP status. Stable across releases and the code to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Use internalCode for programmatic handling, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the error. It is the code the failing system answered with — one of ours where the endpoint publishes one, an operator's own code where the failure came from an operator, and otherwise the request status. Prefer internalCode for branching.

internalCodestring

Names the condition that failed, from our own registry, independently of which system reported it and of the HTTP status. Stable across releases and the code to branch on in client code.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes
messagestringrequired

A human-readable message providing more details about the error.

codestringrequired

A machine-readable code for the specific detail.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes
hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

  • X-Api-Key
  • Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

GET /reports/{reportRunId}
curl https://apiv2.example.com/api/v2/reports/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'
fetch('https://apiv2.example.com/api/v2/reports/3fa85f64-5717-4562-b3fc-2c963f66afa6', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})
requests.get(
    "https://apiv2.example.com/api/v2/reports/3fa85f64-5717-4562-b3fc-2c963f66afa6",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    }
)
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/reports/3fa85f64-5717-4562-b3fc-2c963f66afa6"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
{
  "reportRunId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "reportKey": "subscriber_base_and_revenue",
  "status": "SUCCEEDED",
  "downloadUrl": "https://example-bucket.s3.amazonaws.com/reports/f47ac10b.csv?X-Amz-Signature=...",
  "createdAt": "2024-01-10T08:00:00Z",
  "completedAt": "2024-01-10T08:02:31Z"
}
{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}
{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}
{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}
{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}
{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}