Threads Webfinger Endpoint and Account URI Format Reference

Threads supports the ActivityPub protocol, which allows your public posts to be shared on federated platforms like Mastodon and Pixelfed. To enable this sharing, other servers need to discover your Threads account using a standard called Webfinger. The Webfinger endpoint on Threads returns a JSON resource descriptor that includes your ActivityPub actor URI. This reference article explains the exact format of the Threads Webfinger endpoint URL, the account URI structure, and how to look up any public Threads account from a federated server.

You will learn the correct URL pattern for the Webfinger query, the format of the acct URI, and how the response maps to your ActivityPub actor address. This information is useful for developers building cross-platform tools, for users verifying their account federation status, and for server administrators troubleshooting why a Threads profile does not appear on Mastodon.

What Is the Threads Webfinger Endpoint and Why It Matters

Webfinger is a protocol defined in RFC 7033 that lets a server discover information about an account based on an email-like identifier. In the ActivityPub ecosystem, Webfinger is the first step in resolving a user handle like @username@threads.net into a full ActivityPub actor URL. When a Mastodon server wants to follow or fetch a Threads user, it sends a Webfinger request to Threads and receives a JSON document that contains the user’s ActivityPub actor endpoint.

The Webfinger endpoint on Threads is hosted at a standard path under the threads.net domain. The endpoint accepts a resource query parameter that must be a valid URI in the acct: scheme. The response includes a subject field that echoes the requested resource and an array of links that point to the user’s ActivityPub profile and other services.

Technical Specifications of the Endpoint

The Webfinger endpoint uses HTTPS and returns JSON content type application/jrd+json. The server does not require authentication to query a public account. If the account is private or does not exist, the endpoint returns HTTP 404 or a JSON error response. The endpoint supports CORS, so client-side JavaScript applications can query it directly from a browser.

Account URI Format Rules

The account URI for a Threads user follows the pattern acct:USERNAME@threads.net. The username is the same as the user’s Threads handle without the @ symbol. The URI is case-insensitive on the domain part but usernames on Threads are case-sensitive. The acct: scheme is mandatory. A valid example is acct:zuck@threads.net for Mark Zuckerberg’s account.

How to Query the Threads Webfinger Endpoint

You can query the Webfinger endpoint using any HTTP client, including a browser, curl, or a programming language. The request must be a GET to the well-known URL with the resource parameter. Below are the exact steps to perform a manual query.

1. Obtain the Threads username
   Find the exact username of the account you want to look up. For example, if the profile URL is https://www.threads.net/@zuck, the username is zuck.
2. Construct the Webfinger URL
   Use the format https://www.threads.net/.well-known/webfinger?resource=acct:USERNAME@threads.net. Replace USERNAME with the actual username. Example: https://www.threads.net/.well-known/webfinger?resource=acct:zuck@threads.net.
3. Send the GET request
   Open the URL in a browser or use curl from the command line: curl -H "Accept: application/jrd+json" "https://www.threads.net/.well-known/webfinger?resource=acct:zuck@threads.net".
4. Parse the response
   The JSON response contains a subject field with the acct URI and a links array. The link with rel: "self" and type: "application/activity+json" provides the ActivityPub actor URL, which is typically https://www.threads.net/@USERNAME.

Example Webfinger Response

A successful response for acct:zuck@threads.net returns JSON similar to the following structure (simplified):

{
  "subject": "acct:zuck@threads.net",
  "links": [
    {
      "rel": "self",
      "type": "application/activity+json",
      "href": "https://www.threads.net/@zuck"
    }
  ]
}

The href field in the self link is the ActivityPub actor URI that other servers use to fetch the user’s profile and posts.

Common Issues When Querying Threads Webfinger

Query Returns HTTP 404 for a Valid Username

If the Webfinger endpoint returns a 404 status, the account may be set to private. Threads only exposes Webfinger data for public profiles. Check the account’s privacy setting on Threads. If the account is public and still returns 404, the username may have special characters or leading/trailing spaces. Ensure the username in the acct URI exactly matches the handle shown on the profile page.

Webfinger Returns a Different Subject Than Requested

In rare cases, the subject field may differ slightly from the requested resource. This can happen if the username contains uppercase letters that the server normalizes. For example, requesting acct:Zuck@threads.net might return acct:zuck@threads.net in the subject. This normalization is standard and does not affect functionality.

ActivityPub Actor URL Does Not Load

The self link href returned by Webfinger points to the user’s Threads profile page. That page is an HTML document, not raw ActivityPub JSON. To fetch the ActivityPub actor object, the requesting server must send an HTTP GET with the Accept: application/activity+json header. Without that header, the server returns the HTML page. This is by design and matches how Mastodon and other platforms behave.

Threads Webfinger vs Mastodon Webfinger

Item	Threads	Mastodon
Webfinger endpoint URL	https://www.threads.net/.well-known/webfinger	https://mastodon.example/.well-known/webfinger
Account URI format	acct:USERNAME@threads.net	acct:USERNAME@mastodon.example
Self link rel type	application/activity+json	application/activity+json
Self link href format	https://www.threads.net/@USERNAME	https://mastodon.example/@USERNAME
Private account handling	Returns HTTP 404	Returns HTTP 404 or empty links array

This reference gives you the exact URL patterns and response format needed to query any public Threads account via Webfinger. Use the endpoint URL and acct URI format shown above to integrate Threads discovery into your own tools or to verify that your account is properly federated. For advanced use, note that the self link href is the same as the user’s profile URL and requires the ActivityPub content type header to return the raw actor object.