[Request] Improve Documentation of Usage Tiers to Address User Confusion

Feature Requests
1

Request

I’d like to formally ask the maintainers (@shubhang98) to address the unclear documentation of the new Usage Tiers feature introduced with the Sonar and Sonar-Pro models.

Issue

Usage Tiers were added to the Perplexity API this past week and I’m excited to see these parameters move out of private beta. However, the documentation is not clearly communicating parameters restricted to particular usage tiers in the broader API docs. Users are regularly missing the tiered parameter restrictions with the information contained on just one wiki page, resulting in confusion and frustration.

Discussion Post References

Since the release, multiple users have posted about the API being non-functional when they were simply not in the appropriate usage tier:

  1. Users did not know search domain filters were limited to tier 3.

    • #111
    • #117

  2. Structured outputs have been assumed to be broken, but users were just not in tier 3.

    • #112
    • #128

  3. Returning of related images & related questions were assumed to be broken, but user was not in tier 2.

    • #131

Proposed Solution

  1. Add relevant parameter tier restrictions to the API Reference page.

    • Include a short disclaimer after each parameter description indicating when it’s restricted to certain tiers.
      • Example: “This parameter is only accessible to users in Tier 3. See our Usage Tier Documentation for more information.”
    • This aligns with how the documentation was presented during the closed beta.

  2. Clarify tier requirements in the Structured Outputs Guide.

    • The current note, “Structured outputs is currently a beta feature” does not indicate that it’s available only in Tier 3.
    • In other platforms (for example, OpenAI’s Assistants API), “Beta” merely means features may change or have bugs—not that they’re limited to specific user tiers.

  3. The API should return an error for unauthorized parameter usage.

    • Following the standard set by OpenAI, Anthropic, Azure, Bedrock, etc., the API should respond with an error if a user attempts to use a parameter or model they don’t have access to.
    • Currently, the API silently ignores these parameters, creating confusion for users who assume the parameter is simply “broken” rather than restricted.

Conclusion

Implementing these changes would significantly reduce user confusion and improve the overall experience. New and experienced users alike would benefit from clearer, more consistent documentation—and an error response when they try to use parameters outside their usage tier would make troubleshooting much more straightforward.

Thank you for your time and consideration in resolving these documentation gaps. Please let me know if there is any additional information I can provide to help with these updates.

2

I am Tier 1, but “return_related_questions” and “return_images” work fine in the model “sonar”.
I think that people who have applied in the past can use it regardless of their Tier.

3

Thanks for this post and much appreciated. Will make the changes accordingly.