Pylon
This page provides setup guidance and reference information for the Pylon source connector.
Prerequisites
- An Admin must create a Pylon API token under Settings > Integrations & dev > API tokens. Choose a role that can read the data you’ll sync. Tokens acting as users or bots inherit that identity’s current role and permissions. Pylon tokens don’t have separate scopes. For creation steps, see Pylon’s authentication guide.
- You need access to Tags for the source connection check. You also need access to every selected stream and its parent stream. A successful connection check doesn’t confirm access to every stream.
Set up the connector
Enter only your API Token, without Bearer or surrounding spaces. The connector adds the authentication header to every Pylon API request.
Select Region to match your Pylon tenant and API token. US is the default and 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 your Pylon tenant’s hosted region. Existing configurations without Region continue using US.
You can enter a Start Date in UTC format (YYYY-MM-DDTHH:MM:SSZ). The connector uses each issue’s updated_at, not its creation date. This selects Issues and parent issues for Issue Messages and Issue Threads. Without a date, each sync starts 30 days earlier. Set a date to keep a fixed history window for the child streams. Later incremental Issues syncs continue from the saved cursor.
You can set Number of Workers from 2 to 10. The default is 3. At least two workers let child streams read records while generating parent partitions. Lower this value if other integrations share your organisation’s API allowance.
Sync modes
The Pylon source connector supports these 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 include both boundaries. Each incremental sync can emit issues again at the saved cursor. Adjacent query windows can also replay records at shared edges. Incremental | Append retains these replays as duplicate rows. This includes another copy of an issue at the saved cursor during every sync. Use Incremental | Append + Deduped with id as the primary key to retain one row per issue.
An issue updated exactly at a shared window edge also creates two child partitions. Therefore, Issue Messages and Issue Threads can emit the same child rows twice during one sync. Full Refresh | Overwrite doesn’t deduplicate rows within that sync. With a fixed Start Date, this rare edge case can recur until the issue is updated. No data is lost. If needed, deduplicate child rows downstream using id.
Streams
The Pylon source connector supports these streams:
- Accounts
- Activity Types
- Audit Logs
- Contacts
- Custom Fields
- Issues (Incremental)
- Issue Statuses
- Knowledge Bases
- Macro Groups
- Surveys
- Tags
- Teams
- Ticket Forms
- Training Data
- User Roles
- Users
Stream details
- Audit Logs requires an Admin-role API token and a Pylon plan with audit log access. A 403 response on this stream stops the sync. Deselect the stream if the token isn’t Admin. On Enterprise plans, every sync returns the full audit history. Other plans return a rolling 30-day window. Start Date doesn’t apply. To retain history beyond 30 days, use Full Refresh | Append and deduplicate downstream on
id. Append rewrites the window’s events during every sync. Overwrite modes retain only the current window, which is 30 days on non-Enterprise plans. - Issues is the only incremental stream. It uses
updated_atas its cursor field and thePOST /issues/searchendpoint. Incremental syncs therefore capture every issue modification, not only newly created issues. The connector chooses 30-day query windows. This isn’t a documented Pylon search API limit. Inclusive bounds overlap at window edges to prevent subsecond gaps. The final query can extend one second beyond the cursor interval’s end. Its bounds remain fixed across pages. - Issue Messages and Issue Threads are full-refresh child streams of Issues. Every sync rereads all messages or threads for each issue updated since Start Date. This happens independently of the Issues stream’s saved incremental cursor. Messages and threads aren’t filtered by timestamp, so child records can predate Start Date. Both streams include
issue_id. You can join this field to Issues onid. - Knowledge Base Articles is a full-refresh child stream of Knowledge Bases. It includes
knowledge_base_id, which you can join to Knowledge Bases onid. - Custom Fields retrieves field definitions for three object types: account, issue, and contact. It doesn’t retrieve definitions for other Pylon object types.
- Users includes active and deactivated users.
- Every stream except Issues supports full refresh only and doesn’t save an incremental cursor. Start Date only limits Issues, Issue Messages, and Issue Threads.
Upgrade to 0.0.8
Connector version 0.0.8 switches the Issues stream from GET /issues to POST /issues/search. Its cursor also changes from created_at to updated_at. Incremental syncs therefore capture updates to existing issues, not only newly created issues. Upgrading from any earlier version automatically runs a one-time state migration. The migration rewinds the issues cursor and retrieves history starting from:
- your configured Start Date, if set, or
- 30 days before the first sync, if Start Date is unset.
For a longer backfill, set Start Date before your first sync on 0.0.8. Use the date where you want the backfill to begin. Later syncs use the new updated_at cursor incrementally and don’t retrieve that history again.
Troubleshooting and limitations
Authentication and permissions
- For
wrong_region_token(HTTP 401), set Region to match your Pylon tenant and token. - For
invalid_api_token(HTTP 401), confirm the token is correct and hasn’t been rotated or revoked. If the token has an IP allowlist, permit the public egress IP addresses used by Airbyte. Pylon returns the same error for a blocked IP address. - 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 stops on permission errors instead of silently skipping inaccessible streams.
For other error codes, see Pylon’s error reference.
Rate limits
The Pylon API rate limits apply to each endpoint and are shared by every API token in your organisation:
GET /activity-typesandGET /issue-statuses: 30 requests per minute each.POST /issues/search,GET /issues/{id}/messages,GET /issues/{id}/threads, andGET /knowledge-bases/{id}/articles: 120 requests per minute each.- Other endpoints used by this connector: 300 requests per minute each.
The connector manages request budgets separately for each endpoint. For rate-limited responses (HTTP 429), it first uses Retry-After. If that header is absent, it uses X-Retry-After. If neither is present, it uses exponential backoff and retries up to five times. If the selected retry header specifies 120 seconds or more, the stream stops instead of waiting. The connector uses three workers by default, with a minimum of two and a maximum of ten. Lower Number of Workers if other integrations also use your organisation’s API allowance.
IP allow list
If you use Airbyte Cloud and restrict access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.
Changelog
Expand to review
| Version | Date | Pull Request | Subject |
|---|---|---|---|
| 0.1.0 | 2026-11-10 | 91827 | Add Audit Logs, Macro Groups, Surveys, and Training Data streams, with an Admin-role error message for Audit Logs. |
| 0.0.32 | 2026-11-10 | 91678 | Update dependencies |
| 0.0.31 | 2026-11-06 | 91022 | Add EU region support, documented fields, deactivated users, inclusive issue windows, parent IDs on child streams, actionable errors, request budgets, and configurable concurrency. |
| 0.0.30 | 2026-11-03 | 90398 | Simplify error handling while preserving retry and rate-limit behavior. |
| 0.0.29 | 2026-11-03 | 90704 | Update dependencies |
| 0.0.28 | 2026-10-27 | 90041 | Update dependencies |
| 0.0.27 | 2026-10-20 | 89362 | Update dependencies |
| 0.0.26 | 2026-10-13 | 88765 | Update dependencies |
| 0.0.25 | 2026-10-06 | 87996 | Update dependencies |
| 0.0.24 | 2026-09-29 | 87314 | Update dependencies |
| 0.0.23 | 2026-09-22 | 86771 | Update dependencies |
| 0.0.22 | 2026-09-15 | 86190 | Update dependencies |
| 0.0.21 | 2026-09-08 | 85622 | Update dependencies |
| 0.0.20 | 2026-08-18 | 84722 | Update dependencies |
| 0.0.19 | 2026-08-11 | 84079 | Update dependencies |
| 0.0.18 | 2026-07-28 | 83194 | Update to CDK 7.23.8 (fixes AirbyteCustomCodeNotPermittedError for bundled custom components) and remove the temporary Cloud version override |
| 0.0.17 | 2026-07-28 | 1082 | Roll Cloud back to 0.0.15 — 0.0.16 is built on SDM 7.23.7, which breaks bundled custom components |
| 0.0.16 | 2026-07-28 | 83064 | Update dependencies |
| 0.0.15 | 2026-07-21 | 82527 | Update dependencies |
| 0.0.14 | 2026-07-14 | 81963 | Update dependencies |
| 0.0.13 | 2026-06-30 | 81204 | Update dependencies |
| 0.0.12 | 2026-06-23 | 80608 | Update dependencies |
| 0.0.11 | 2026-06-16 | 80004 | Update dependencies |
| 0.0.10 | 2026-06-09 | 79462 | Update dependencies |
| 0.0.9 | 2026-06-02 | 78905 | Update dependencies |
| 0.0.8 | 2026-05-07 | 76083 | Switch 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.7 | 2026-04-28 | 77394 | Update dependencies |
| 0.0.6 | 2026-04-21 | 76721 | Update dependencies |
| 0.0.5 | 2026-03-31 | 75855 | Update dependencies |
| 0.0.4 | 2026-03-17 | 74921 | Update dependencies |
| 0.0.3 | 2026-02-24 | 73850 | Update dependencies |
| 0.0.2 | 2026-02-20 | 73693 | Make start_date optional, default to 1 month ago |
| 0.0.1 | 2026-02-20 | 73624 | Initial release of Pylon source connector |