Here is my proof of concept code –
import asyncio
import os
from dotenv import load_dotenv
from openai import AsyncOpenAI
async def main():
client = AsyncOpenAI(
api_key=os.getenv("PERPLEXITY_API_KEY"),
base_url="https://api.perplexity.ai"
)
response = await client.chat.completions.create(
model="sonar-pro",
messages=[
{"role": "system", "content": "Be precise and concise."},
{"role": "user", "content": "How many stars are there in our galaxy?"}
],
stream=True
)
async for event in response:
print(event)
if __name__ == "__main__":
load_dotenv(".env.local")
asyncio.run(main())
Last event in the stream –
(newlines inserted for read-ability)
ChatCompletionChunk(
id='d14cd700-0e62-4374-9583-c191d5a110f4', choices=[
Choice(
delta=ChoiceDelta(
content='[4].',
function_call=None,
refusal=None,
role='assistant',
tool_calls=None
),
finish_reason=None,
index=0,
logprobs=None,
message={
'role': 'assistant',
'content': 'The best current estimates suggest the Milky Way contains **between 200 billion and 400 billion stars**, with 200 billion being a commonly cited figure but the total possibly as high as 400 billion due to uncertainties involving faint, low-mass red dwarf stars[1][2][3][4].\n\nThis uncertainty primarily arises from the difficulty in detecting very dim, low-mass stars—especially red dwarfs—which are extremely abundant but hard to observe directly[1][3]. Older estimates placed the number closer to 100 billion, but newer data from astronomical surveys like ESA’s Gaia mission suggest that number is likely too low and has been revised upward[1]. The exact count remains elusive, as ongoing studies continue to resolve these uncertainties.\n\nIn summary, while the precise number of stars in the Milky Way is not known for certain, **current scientific consensus places the count probably between 200–400 billion**[1][2][3][4].'
}
)
],
created=1755887465,
model='sonar-pro',
object='chat.completion',
service_tier=None,
system_fingerprint=None,
usage=CompletionUsage(
completion_tokens=200,
prompt_tokens=14,
total_tokens=214,
completion_tokens_details=None,
prompt_tokens_details=None,
search_context_size='low'
),
citations=[
'https://bigthink.com/starts-with-a-bang/how-many-stars-milky-way/',
'https://www.youtube.com/watch?v=MTeyypxmbK0',
'https://www.youtube.com/watch?v=hiWacnGH5II',
'https://en.wikipedia.org/wiki/Milky_Way',
'https://imagine.gsfc.nasa.gov/science/objects/milkyway1.html'
],
search_results=[
{
'title': "Why we still don't know how many stars are in the Milky Way",
'url': 'https://bigthink.com/starts-with-a-bang/how-many-stars-milky-way/',
'date': '2025-04-02',
'last_updated': '2025-06-16'
},
{
'title': 'How Many Stars Are in the Universe!?!?',
'url': 'https://www.youtube.com/watch?v=MTeyypxmbK0',
'date': '2025-05-24',
'last_updated': '2025-08-19'
},
{
'title': 'How Many STARS Are In The MILKY WAY?',
'url': 'https://www.youtube.com/watch?v=hiWacnGH5II',
'date': '2024-03-22',
'last_updated': '2025-07-01'
},
{
'title': 'Milky Way',
'url': 'https://en.wikipedia.org/wiki/Milky_Way',
'date': '2001-09-15',
'last_updated': '2025-08-18'
},
{
'title': 'Milky Way Galaxy - Imagine the Universe! - NASA',
'url': 'https://imagine.gsfc.nasa.gov/science/objects/milkyway1.html',
'date': '2015-07-22',
'last_updated': '2025-08-11'
}
]
)
ChatCompletionChunk(
id='d14cd700-0e62-4374-9583-c191d5a110f4',
choices=[
Choice(
delta=ChoiceDelta(
content='',
function_call=None,
refusal=None,
role='assistant',
tool_calls=None
),
finish_reason='stop',
index=0,
logprobs=None,
message={
'role': 'assistant',
'content':
"""The best current estimates suggest the Milky Way contains **between 200 billion and 400 billion stars**, with 200 billion being a commonly cited figure but the total possibly as high as 400 billion due to uncertainties involving faint, low-mass red dwarf stars[1][2][3][4].
This uncertainty primarily arises from the difficulty in detecting very dim, low-mass stars—especially red dwarfs—which are extremely abundant but hard to observe directly[1][3]. Older estimates placed the number closer to 100 billion, but newer data from astronomical surveys like ESA’s Gaia mission suggest that number is likely too low and has been revised upward[1]. The exact count remains elusive, as ongoing studies continue to resolve these uncertainties.
In summary, while the precise number of stars in the Milky Way is not known for certain, **current scientific consensus places the count probably between 200–400 billion**[1][2][3][4]."""
}
)
],
created=1755887465,
model='sonar-pro',
object='chat.completion',
service_tier=None,
system_fingerprint=None,
usage=CompletionUsage(
completion_tokens=200,
prompt_tokens=14,
total_tokens=214,
completion_tokens_details=None,
prompt_tokens_details=None,
search_context_size='low',
cost={
'input_tokens_cost': 0.0,
'output_tokens_cost': 0.003,
'request_cost': 0.006,
'total_cost': 0.009
}
),
citations=[
'https://bigthink.com/starts-with-a-bang/how-many-stars-milky-way/',
'https://www.youtube.com/watch?v=MTeyypxmbK0',
'https://www.youtube.com/watch?v=hiWacnGH5II',
'https://en.wikipedia.org/wiki/Milky_Way',
'https://imagine.gsfc.nasa.gov/science/objects/milkyway1.html'
],
search_results=[{
'title': "Why we still don't know how many stars are in the Milky Way",
'url': 'https://bigthink.com/starts-with-a-bang/how-many-stars-milky-way/',
'date': '2025-04-02',
'last_updated': '2025-06-16'
},
{
'title': 'How Many Stars Are in the Universe!?!?',
'url': 'https://www.youtube.com/watch?v=MTeyypxmbK0',
'date': '2025-05-24',
'last_updated': '2025-08-19'
},
{
'title': 'How Many STARS Are In The MILKY WAY?',
'url': 'https://www.youtube.com/watch?v=hiWacnGH5II',
'date': '2024-03-22',
'last_updated': '2025-07-01'
},
{
'title': 'Milky Way',
'url': 'https://en.wikipedia.org/wiki/Milky_Way',
'date': '2001-09-15',
'last_updated': '2025-08-18'
},
{
'title': 'Milky Way Galaxy - Imagine the Universe! - NASA',
'url': 'https://imagine.gsfc.nasa.gov/science/objects/milkyway1.html',
'date': '2015-07-22',
'last_updated': '2025-08-11'
}]
)
The search results and citations both have a list of items. The model response has 5 citations. From another thread it looks like this a known issue.
Questions
- Is it safe to assume that the search results and citations are always the same set and in the same order?
- Are these lists 1-indexed when referenced by the model. e.g. The model’s
[1]reference in thecontentis referring tosearch_results[0]andcitations[0]?
I couldn’t find clear documentation on these items
Edit:
It would be nice if Perplexity provided a customized Python type that matches the API return. Right now I’m having to roll my own based on openai.types.chat.ChatCompletionChunk