Custom REST source

The Custom REST source lets you connect any REST API to PostHog's Data Warehouse without waiting for a dedicated integration. You configure the connection using the source builder in the PostHog UI – setting the base URL, authentication, pagination, and the streams (endpoints) you want to sync – and PostHog handles the rest.

This is useful when:

• The API you need isn't available as a managed source
• You want to prototype a connection quickly
• You need to pull data from an internal or niche API

Create a custom REST source

1. In PostHog, go to the Data pipeline sources tab.
2. Click + New source and select Custom REST source.
3. Configure your source using the builder (see Configuration reference below):
   • Enter the Base URL for the API (e.g. https://api.example.com/v1)
   • Select your Authentication type and enter your credentials
   • Add any Default headers the API requires
   • Add one or more Streams – each stream maps an API endpoint to a table in your Data Warehouse
4. Click Next. PostHog validates the configuration, checks that the URLs are reachable, and probes the first few endpoints to confirm your credentials work.
5. Configure sync settings (sync method, frequency) for each stream, then start syncing.

Configuration reference

Base URL

The root URL that all stream paths are resolved against (e.g. https://api.example.com/v1). On PostHog Cloud, all URLs must use https://.

Authentication

Select an authentication type from the Authentication dropdown.

Credentials are stored encrypted and never exposed in API responses.

OAuth2 configuration

OAuth2 authentication supports two grant types:

• client_credentials – Machine-to-machine authentication. The source exchanges the client ID and client secret for an access token. No user interaction is required.
• refresh_token – The source uses a pre-obtained refresh token (along with the client ID and secret) to mint access tokens. Use this for APIs where you've already completed an authorization flow outside PostHog.

The authorization_code grant is not supported.

Default headers

Optional key-value pairs sent with every request. Auth headers are added automatically based on your authentication configuration – you don't need to duplicate them here.

Streams

Each stream maps an API endpoint to a table in your Data Warehouse. You can add up to 50 streams per source.

Click Add stream to add a new stream. Each stream has the following fields:

Pagination

Select a Paginator type for each stream. This tells PostHog how to fetch all pages of data from the endpoint.

Incremental sync

Enable Incremental sync on a stream to only fetch new or updated records on subsequent syncs instead of re-fetching everything.

Example configurations

Paginated API with bearer token

To sync users and orders from an API that uses cursor pagination:

1. Set Base URL to https://api.myservice.com/v2
2. Set Authentication to Bearer token and enter your token
3. Add a stream named users with path /users and Cursor in JSON body pagination (cursor JSONPath: meta.next_cursor, cursor query param: cursor)
4. Add a second stream named orders with the same pagination. Enable Incremental sync with cursor JSONPath updated_at and cursor query param updated_since

API key in query parameter

To sync contacts from an API that authenticates via a query parameter:

1. Set Base URL to https://data.example.com/api
2. Set Authentication to API key, location to Query parameter, parameter name to apikey, and enter your key
3. Add a stream named contacts with path /contacts, records JSONPath results, and Offset / limit query params pagination (page size: 200)

POST-based query endpoint

Some APIs require POST requests to query data. The builder supports this:

1. Set Base URL to https://analytics.example.com
2. Set Authentication to Bearer token and enter your token
3. Add a stream named events with path /query/events and HTTP method POST
4. Set the paginator to JSON body next-URL with next-URL JSONPath next_page_url

Limitations

• Maximum 5 custom sources per team
• Maximum 50 streams per source
• Only GET and POST HTTP methods are supported
• All URLs must use https:// on PostHog Cloud
• URLs pointing to internal or private network hosts are blocked on PostHog Cloud

Troubleshooting

Credential validation fails at creation

PostHog probes the first few endpoints when you create a source. If the API returns HTTP 401 or 403, check that:

• You selected the correct authentication type
• The credentials you entered are valid and have the required permissions
• For API key auth, the location and parameter name match what the API expects

Other status codes (404, 429, 5xx) don't block source creation – those errors surface on the first sync instead.

Validation errors

Common issues:

• Missing base URL – The base URL is required
• No streams – You need at least one stream
• Duplicate stream names – Each stream name must be unique
• Invalid HTTP method – Only GET and POST are supported

Incremental sync skips rows

If using Ascending upstream row order (the default) and the API doesn't guarantee ascending order by the cursor field, rows can be skipped when a sync is interrupted and resumed. Set Upstream row order to Descending if the API returns newest records first.

OAuth2 token errors

If an OAuth2 source's token expires or is revoked, the source fails with a TOKEN_REFRESH_FAILED error. To reconnect:

1. Edit the source settings.
2. Re-enter the Client secret and (for refresh_token grant sources) the Refresh token.
3. Save the source. PostHog validates the new credentials and clears the error once a token is successfully minted.

Have a question? Ask PostHog AI