Skip to main content

Linear

Availability
Available CoreAvailable StandardAvailable PlusAvailable ProAvailable Enterprise FlexAvailable Self-Managed EnterpriseAvailable PyAirbyte
Support Level
Marketplace
Connector Version
0.2.4 (last updated a day ago)
Sync Success Rate
Usage Rate
Data workers used
0.2 per sync (Learn more)
Definition ID
1c5d8316-ed42-4473-8fbc-2626f03f070c

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

Linear is a project management and issue tracking tool designed for software teams. It provides a streamlined interface for managing issues, sprints, and product roadmaps with a focus on speed and simplicity.

Prerequisites​

  • A Linear account
  • One of the following authentication methods:
    • API Key: A Linear personal API key.
    • OAuth 2.0: A Linear OAuth app with a client ID, client secret, and refresh token.

Setup guide​

Step 1: Choose an authentication method​

The Linear source connector supports API key and OAuth 2.0 authentication.

API key​

  1. Log in to your Linear account.
  2. Navigate to Settings by clicking your workspace name in the sidebar.
  3. Select Security & access from the settings menu.
  4. Scroll to the Personal API keys section.
  5. Click Create key, give the key a descriptive label (for example, airbyte), and click Create.
  6. Copy the API key and store it securely. Linear only displays the key once.

The API key inherits your user's permissions in the workspace. The connector can only sync data you can see in Linear.

For more information, see the Linear GraphQL API documentation.

OAuth 2.0​

Create a Linear OAuth app and configure the redirect callback URL for your Airbyte deployment. The connector requests the read and customer:read scopes. Linear returns an access token and refresh token after the OAuth flow, and the connector uses the refresh token to refresh access tokens when they expire.

For more information, see the Linear OAuth 2.0 authentication documentation.

Step 2: Configure the Linear connector in Airbyte​

  1. In the Airbyte UI, navigate to Sources and click + New source.
  2. Select Linear from the list of available sources.
  3. Enter a Source name of your choosing.
  4. For Authentication, choose API Key or OAuth 2.0.
  5. Enter the required credentials for your authentication method.
  6. Optionally, enter a Start Date in ISO 8601 format (for example, 2024-01-01T00:00:00.000Z). Only records updated on or after this date are replicated for streams that support incremental sync. If you leave this field empty, the connector defaults to two years before the time of the first sync.
  7. Optionally, adjust the Number of concurrent workers (default 4, range 1–10). Higher values speed up syncs but increase the risk of hitting Linear's rate limits. Users on API key authentication (2,500 requests/hour) should generally stay at or below the default. Users on OAuth authentication (5,000 requests/hour) may increase this value if they have observed headroom in their rate-limit usage.
  8. Click Set up source and wait for the connection test to complete.

Existing connections that authenticated with a Linear API key continue to use API key authentication after upgrading to connector version 0.2.1 or later. If you upgraded an API key connection to 0.2.0 and it no longer passes connection checks, upgrade to 0.2.1 or later.

Supported sync modes​

The Linear source connector supports the following sync modes:

Streams that support incremental sync use the updatedAt field as the cursor. The Start Date you set when configuring the connector is the lower bound for the first incremental sync. Subsequent syncs use the most recent updatedAt value from the previous sync as the new lower bound.

The following streams are full-refresh only because the Linear GraphQL API doesn't expose a filter argument that the connector can use to request only updated records: project_statuses, issue_relations, customer_statuses, and customer_tiers.

Supported streams​

The Linear source connector supports the following streams. Streams marked as incremental use updatedAt as the cursor field.

StreamIncrementalDescription
attachmentsYesFile and link attachments on issues.
commentsYesComments posted on issues.
customer_needsYesCustomer needs associated with issues.
customersYesCustomer records tracked in Linear's customer requests feature.
customer_statusesNoStatus definitions for customer records.
customer_tiersNoTier definitions for customer records.
cyclesYesCycles (sprints) for each team.
issue_labelsYesLabels that can be applied to issues.
issue_relationsNoRelationships between issues (for example, blocks and duplicates).
issuesYesIssues in every team, including archived issues.
project_milestonesYesMilestones defined inside projects.
project_statusesNoStatus definitions for projects.
projectsYesProjects across all teams.
teamsYesTeams in your Linear workspace.
usersYesUsers in your Linear workspace.
workflow_statesYesWorkflow states (for example, Todo, In Progress, Done) defined by each team.

Limitations and troubleshooting​

Rate limiting​

The Linear API uses a leaky bucket algorithm for rate limiting. The connector detects rate-limit errors returned by the API and automatically backs off until the rate-limit window resets. Syncs may slow down during backoff periods but will resume without manual intervention.

Linear enforces three types of rate limits:

  • Request limits: 2,500 requests per user per hour for API key authentication, 5,000 for OAuth app authentication. All requests by the same user share the same quota.
  • Endpoint-specific limits: Certain queries have lower per-endpoint limits. The connector respects the X-RateLimit-Endpoint-Requests-Reset header when these are hit.
  • Complexity limits: Each query's complexity is calculated based on the number of requested fields and pagination depth. The maximum single-query complexity is 10,000 points. The hourly complexity budget is 3,000,000 points for API key authentication and 2,000,000 for OAuth.

Workspace-level OAuth applications receive dynamically increased limits based on the number of paid seats. For more information, see the Linear rate limiting documentation.

Data availability​

The connector retrieves data that the authenticated user has access to. If you cannot see certain teams, projects, or issues in your synced data, verify that your Linear account has the appropriate permissions.

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​

This connector uses the Linear GraphQL API. All API requests use the https://api.linear.app/graphql endpoint.

For programmatic configuration, use these parameter names:

FieldRequiredDescription
credentials.auth_typeYesAuthentication method. Valid values are API Key and OAuth2.0.
credentials.api_keyRequired for API key authenticationLinear personal API key.
credentials.client_idRequired for OAuth 2.0 authenticationClient ID of your Linear OAuth app.
credentials.client_secretRequired for OAuth 2.0 authenticationClient secret of your Linear OAuth app.
credentials.refresh_tokenRequired for OAuth 2.0 authenticationRefresh token returned by the Linear OAuth flow.
start_dateNoUTC date and time in ISO 8601 format. Records updated before this date aren't replicated for streams that support incremental sync. If unset, defaults to two years before the first sync.
num_workersNoNumber of worker threads used to read streams in parallel (default 4, range 1–10). Higher values speed up syncs but increase the risk of hitting rate limits.

Reference​

Config fields reference

Field
Type
Property name
object
credentials
integer
num_workers
string
start_date

Changelog​

Expand to review
VersionDatePull RequestSubject
0.2.52026-06-1078237fix(source-linear): Handle GraphQL rate-limit errors
0.2.42026-06-0979388Update dependencies
0.2.32026-06-0278816Update dependencies
0.2.22026-05-1878160Promoted release candidate to GA
0.2.2-rc.22026-05-1578124Expose num_workers in connector spec (default 4, min 1, max 10) so users can override the per-connection concurrency from the UI
0.2.2-rc.12026-05-1278034Resume concurrency tuning at default_concurrency=4 (Path A, 2,500 req/hr API key ceiling); re-enable progressive rollout
0.2.12026-05-1278013Fix API key config migration for existing connections
0.2.02026-05-1177578Add OAuth 2.0 authentication support and migrate existing API key configurations to nested credentials
0.1.22026-04-2877318Update dependencies
0.1.12026-04-2176654Update dependencies
0.1.02026-04-1776429Add incremental sync support for 12 streams using the updatedAt cursor field
0.0.362026-03-3175720Update dependencies
0.0.352026-03-1775023Update dependencies
0.0.342026-03-0374239Update dependencies
0.0.332026-02-1073035Update dependencies
0.0.322026-02-0372748Update dependencies
0.0.312026-01-2172240fix(linear): icon
0.0.302026-01-2072027Update dependencies
0.0.292026-01-1471489Update dependencies
0.0.282025-12-1870775Update dependencies
0.0.272025-11-2570007Update dependencies
0.0.262025-11-1869442Update dependencies
0.0.252025-10-2968966Update dependencies
0.0.242025-10-2168296Update dependencies
0.0.232025-10-1468027Update dependencies
0.0.222025-10-0767519Update dependencies
0.0.212025-09-3066807Update dependencies
0.0.202025-09-2466655Update dependencies
0.0.192025-09-0965897Update dependencies
0.0.182025-08-2365391Update dependencies
0.0.172025-08-0964629Update dependencies
0.0.162025-08-0264275Update dependencies
0.0.152025-07-2663892Update dependencies
0.0.142025-07-1963518Update dependencies
0.0.132025-07-1263095Update dependencies
0.0.122025-07-0562601Update dependencies
0.0.112025-06-2862178Update dependencies
0.0.102025-06-2661417source-linear contribution from zckymc
0.0.92025-06-2161843Update dependencies
0.0.82025-06-1461117Update dependencies
0.0.72025-05-2460728Update dependencies
0.0.62025-05-1059893Update dependencies
0.0.52025-05-0359299Update dependencies
0.0.42025-04-2658781Update dependencies
0.0.32025-04-1958215Update dependencies
0.0.22025-04-1257669Update dependencies
0.0.12025-04-11#57586Initial release by @natikgadzhi
Was this page helpful?