Skip to main content

Pylon

This page contains the setup guide and reference information for the Pylon source connector.

Prerequisites​

  • A Pylon API token created by an Admin under Settings > Integrations & dev > API tokens. Choose a role that can read the data you plan to sync. If the token acts as a user or bot, it inherits that identity's current role and permissions. Pylon tokens have no separate scopes. For creation steps, see Pylon's authentication guide.
  • Access to Tags for the source connection check, plus access to each selected stream and its parent stream. A successful connection check does not verify access to every stream.

Setup guide​

Before you set up the source, create a Pylon API token with a role that can read the data you plan to sync, as described in Prerequisites. For creation steps, see Pylon's authentication guide.

Set up Pylon​

For Airbyte Cloud​

  1. Log in to your Airbyte Cloud account.
  2. Click Sources, then click + New source.
  3. Select Pylon as the source type.
  4. Enter a name for the Pylon connector.
  5. Fill in the fields described below.
  6. Click Set up source.

For Airbyte Open Source​

  1. Navigate to the Airbyte Open Source dashboard.
  2. Click Sources, then click + New source.
  3. Select Pylon as the source type.
  4. Enter a name for the Pylon connector.
  5. Fill in the fields described below.
  6. Click Set up source.

Enter only your API Token, without the word Bearer or surrounding spaces. The connector adds the authentication header to all requests to the Pylon API.

Select Region to match your Pylon tenant and API token. US (the default) uses https://api.usepylon.com with tokens prefixed pylon_api_. EU uses https://api.eu.usepylon.com with tokens prefixed pylon_api_eu_. For older tokens without a prefix, choose the region where your Pylon tenant is hosted. Existing configurations without Region continue to use US.

Optionally, enter a Start Date in UTC format (YYYY-MM-DDTHH:MM:SSZ). The connector uses the issue's updated_at, not its creation date, to select Issues and the parent issues for Issue Messages and Issue Threads. If omitted, the starting point defaults to 30 days before each sync. Set an explicit date to keep a fixed history window for the child streams. Subsequent incremental Issues syncs resume from the saved cursor.

Optionally, set Number of Workers from 2 to 10 (default: 3). At least two workers are required so child streams can read records while generating parent partitions. Lower this value if other integrations share your organization's API allowance.

Supported sync modes​

The Pylon source connector supports the following sync modes:

  • Full Refresh | Overwrite
  • Full Refresh | Append
  • Incremental Sync | Append (Issues stream only)
  • Incremental Sync | Append + Deduped (Issues stream only; recommended)

Issue time filters are inclusive. Each incremental sync can re-emit issues at the saved cursor, and adjacent query windows can replay records at their shared edges. Incremental | Append retains these replays as duplicate rows, including another copy each sync of an issue at the saved cursor. Use Incremental | Append + Deduped, with id as the primary key, to keep one row per issue.

An issue updated exactly at a shared window edge also generates two child partitions. Issue Messages and Issue Threads can therefore emit the same child rows twice within one sync. Full Refresh | Overwrite does not deduplicate rows within that sync. With a fixed Start Date, this rare edge case can recur on every sync until the issue is updated. It does not lose data; deduplicate child rows downstream by id if needed.

Supported Streams​

StreamPylon API endpointSync modesPrimary keyParent stream (join key)
AccountsGET /accountsFull RefreshidNone
Activity TypesGET /activity-typesFull RefreshidNone
Audit LogsGET /audit-logsFull RefreshidNone
ContactsGET /contactsFull RefreshidNone
Custom FieldsGET /custom-fieldsFull RefreshidNone
IssuesPOST /issues/searchFull Refresh, Incremental (updated_at)idNone
Issue MessagesGET /issues/{id}/messagesFull RefreshidIssues (issue_id = Issues id)
Issue ThreadsGET /issues/{id}/threadsFull RefreshidIssues (issue_id = Issues id)
Issue StatusesGET /issue-statusesFull RefreshslugNone
Knowledge BasesGET /knowledge-basesFull RefreshidNone
Knowledge Base ArticlesGET /knowledge-bases/{id}/articlesFull RefreshidKnowledge Bases (knowledge_base_id = Knowledge Bases id)
Macro GroupsGET /macro-groupsFull RefreshidNone
SurveysGET /surveysFull RefreshidNone
TagsGET /tagsFull RefreshidNone
TeamsGET /teamsFull RefreshidNone
Ticket FormsGET /ticket-formsFull RefreshidNone
Training DataGET /training-dataFull RefreshidNone
User RolesGET /user-rolesFull RefreshidNone
UsersGET /usersFull RefreshidNone

Stream notes​

  • Audit Logs requires an Admin-role API token and a Pylon plan that includes audit log access. A 403 on this stream fails the sync; deselect it if the token isn't Admin. Enterprise organizations get the full audit history on every sync; other plans get a rolling window of the last 30 days. Start Date does not apply. Use Full Refresh | Append, de-duplicating on id downstream, to keep history beyond 30 days. Append re-writes the window's events on each sync. Overwrite modes keep only the current window (30 days on non-Enterprise plans).
  • Issues is the only incremental stream. It uses updated_at as its cursor field and the POST /issues/search endpoint, so incremental syncs capture all issue modifications, not just newly created issues. The connector chooses 30-day query windows; this is not a documented Pylon search API limit. Inclusive bounds overlap at window edges to avoid subsecond gaps. The final query can extend up to one second beyond the cursor interval's end, and its bounds remain fixed across pages.
  • Issue Messages and Issue Threads are full-refresh child streams of Issues. On every sync, they re-read all messages or threads for each issue updated since Start Date, independently of the Issues stream's saved incremental cursor. They do not filter on the message or thread timestamp, so child records can predate Start Date. Both streams include issue_id, which you can join to Issues on id.
  • Knowledge Base Articles is a full-refresh child stream of Knowledge Bases. It includes knowledge_base_id, which you can join to Knowledge Bases on id.
  • Custom Fields retrieves field definitions for three object types: account, issue, and contact. It does not retrieve definitions for other Pylon object types.
  • Users includes both active and deactivated users.
  • Issue Statuses uses slug as its primary key because issue status records have no id field.
  • Macro Groups returns macro groups only, not the macros in them. Surveys returns survey definitions, not survey responses. Training Data returns training data configurations. Pylon doesn't paginate these three endpoints, so the connector reads each in a single request.
  • Tags returns tags for every object type in one stream. Use object_type (for example account, article, or issue) to tell them apart.
  • Teams includes each team's members in a nested users array, plus its assignment settings. The connector has no separate team membership stream.
  • All streams other than Issues support full refresh only and do not save an incremental cursor. Start Date does not limit streams other than Issues, Issue Messages, and Issue Threads.

Upgrade notes​

Upgrading to 1.0.0​

Version 1.0.0 is a breaking change: tags on Accounts and Issues is now an array of strings, and eight timestamp fields on Accounts, Issues, Issue Messages, and Custom Fields are now typed as date-time. After upgrading, refresh the source schema; some destinations also require you to clear the affected streams. For the changed fields and upgrade steps, see the Pylon migration guide.

Upgrading to 0.0.8​

Connector version 0.0.8 switches the Issues stream from GET /issues (cursored on created_at) to POST /issues/search (cursored on updated_at) so that incremental syncs capture updates to existing issues, not just newly created ones. Connections upgrading from any earlier version automatically run a one-time state migration that rewinds the issues cursor and re-pulls history starting from:

  • the Start Date you configured, if it is set, or
  • 30 days before the first sync, if Start Date is unset.

If you need a longer backfill, set Start Date to the desired date before the first sync on 0.0.8. Subsequent syncs use the new updated_at cursor incrementally and do not re-pull history.

Limitations & Troubleshooting​

Authentication and permissions​

  • For wrong_region_token (HTTP 401), change Region to match your Pylon tenant and token.
  • For invalid_api_token (HTTP 401), check that the token is correct and has not been rotated or revoked. If the token has an IP allowlist, allow the public egress IP addresses used by Airbyte. Pylon returns the same error when an IP address is blocked.
  • For HTTP 403, give the token's role read access to the affected data, or deselect the stream. Child streams also require access to their parent data. The connector fails on permission errors rather than silently skipping inaccessible streams.

For other error codes, see Pylon's error reference.

Rate limiting​

The Pylon API rate limits apply per endpoint and are shared by all API tokens in your organization:

  • GET /activity-types and GET /issue-statuses: 30 requests per minute each.
  • POST /issues/search, GET /issues/{id}/messages, GET /issues/{id}/threads, and GET /knowledge-bases/{id}/articles: 120 requests per minute each.
  • Other endpoints used by this connector: 300 requests per minute each.

The connector budgets requests separately for each endpoint. For rate-limited responses (HTTP 429), it uses Retry-After, then X-Retry-After if the first header is absent, then exponential backoff if neither is present, with up to five retries. A selected retry-header wait of 120 seconds or more stops the stream rather than waiting. By default, the connector uses three workers, with a minimum of two and a maximum of ten. Lower Number of Workers if other integrations also use your organization's API allowance.

IP allow list​

If you use Airbyte Cloud and your organization restricts access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.

Reference​

Config fields reference

Field
Type
Property name
string
api_token
integer
num_workers
string
region
string
start_date

Changelog​

Expand to review
VersionDatePull RequestSubject
1.0.12026-11-1392973Mark the connector as certified
1.0.02026-11-1292021Type tags as strings and 8 timestamp fields as date-time
0.1.02026-11-1091827Add Audit Logs, Macro Groups, Surveys, and Training Data streams, with an Admin-role error message for Audit Logs.
0.0.322026-11-1091678Update dependencies
0.0.312026-11-0691022Add EU region support, documented fields, deactivated users, inclusive issue windows, parent IDs on child streams, actionable errors, request budgets, and configurable concurrency.
0.0.302026-11-0390398Simplify error handling while preserving retry and rate-limit behavior.
0.0.292026-11-0390704Update dependencies
0.0.282026-10-2790041Update dependencies
0.0.272026-10-2089362Update dependencies
0.0.262026-10-1388765Update dependencies
0.0.252026-10-0687996Update dependencies
0.0.242026-09-2987314Update dependencies
0.0.232026-09-2286771Update dependencies
0.0.222026-09-1586190Update dependencies
0.0.212026-09-0885622Update dependencies
0.0.202026-08-1884722Update dependencies
0.0.192026-08-1184079Update dependencies
0.0.182026-07-2883194Update to CDK 7.23.8 (fixes AirbyteCustomCodeNotPermittedError for bundled custom components) and remove the temporary Cloud version override
0.0.172026-07-281082Roll Cloud back to 0.0.15 — 0.0.16 is built on SDM 7.23.7, which breaks bundled custom components
0.0.162026-07-2883064Update dependencies
0.0.152026-07-2182527Update dependencies
0.0.142026-07-1481963Update dependencies
0.0.132026-06-3081204Update dependencies
0.0.122026-06-2380608Update dependencies
0.0.112026-06-1680004Update dependencies
0.0.102026-06-0979462Update dependencies
0.0.92026-06-0278905Update dependencies
0.0.82026-05-0776083Switch the Issues stream to POST /issues/search cursored on updated_at for true incremental sync. State migration rewinds the issues cursor to the configured Start Date (or 30 days ago if unset) on the first sync after upgrade.
0.0.72026-04-2877394Update dependencies
0.0.62026-04-2176721Update dependencies
0.0.52026-03-3175855Update dependencies
0.0.42026-03-1774921Update dependencies
0.0.32026-02-2473850Update dependencies
0.0.22026-02-2073693Make start_date optional, default to 1 month ago
0.0.12026-02-2073624Initial release of Pylon source connector