paperqa-api

Python client for interacting with the PaperQA server

Installation

Python 3.11+ is required for this package

pip install pqapi

Authentication

Make sure to set the environment variable PQA_API_KEY to your API token:

export PQA_API_KEY=pqa-...

API keys generally have a rate limit associated with them that is based on queries per day. These are based on a rolling window, rather than resetting at a specific time. You will receive 429s if you have exceeded your rate limit on submission.

Basic Usage

Simple Synchronous Queries

The simplest way to use the API is with synchronous queries:

import pqapi

response = pqapi.agent_query("Are COVID-19 vaccines effective?")

print(response.answer)

Async Queries

You can also make asynchronous queries:

import pqapi

response = await pqapi.async_agent_query(query)

These still require an open connection though, so do not accumulate too many of them. Each query takes between 1 and 5 minutes generally.

Advanced Features

Batch Job Processing

For running multiple long-running queries efficiently, use the job submission API:

import asyncio
import pqapi

# Define multiple queries
queries = [
    'What is the elastic modulus of gold?',
    'What is the elastic modulus of silver?',
    'What is the elastic modulus of copper?'
]

# Submit jobs
jobs = [pqapi.submit_agent_job(query=q) for q in queries]

# Poll for results
results = asyncio.run(pqapi.gather_pqa_results_via_polling(
    [job['metadata']['query_id'] for job in jobs]
))

The results will include:

question: Your original query text
request: Serialized settings used in your query
response: Serialized pqapi.AnswerResponse object

Using Templates

You can use predefined templates that you develop and save on paperqa.app:

# Single query with template
response = pqapi.agent_query(
    'The melting point of gold is 1000F.',
    named_template='check for contradiction'
)

# Batch jobs with templates
contradictions = [
    {
        'query': 'Gold can be transmuted into platinum.',
        'named_template': 'check for contradiction'
    },
]
contradiction_jobs = [pqapi.submit_agent_job(**c) for c in contradictions]
results = asyncio.run(pqapi.gather_pqa_results_via_polling(
    [job['metadata']['query_id'] for job in contradiction_jobs]
))

AnswerResponse Object

The response object contains detailed information about your query:

Sources used
Cost information
Other metadata

Access the main specific answer text with:

print(response.answer)

Metadata

Release files for pqapi 7.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pqapi 7.4.0
File	Size	Uploaded
pqapi-7.4.0.tar.gz	1.6 MB	Jul 29, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for pqapi 7.4.0
File	Interpreter	ABI	Platform	Reset
pqapi-7.4.0-py3-none-any.whl 14.1 kB Jul 29, 2025	Python 3	none	any	Details

Total release size: 1.6 MB

Release files / pqapi-7.4.0.tar.gz

Download URL	pqapi-7.4.0.tar.gz
Size	1.6 MB
Tags	Source
SHA-256 checksum How to use checksums	`34a59ce521554a796a4f767cd2c5570bb86f87a0ee6188ef1fa33e3e0063499a`
BLAKE2b-256 checksum How to use checksums	`814dba3c533ad51ec821d1744185adebd8e14e9a92eb58c86f714ba9b83179d4`
Upload date	Jul 29, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.12.9`

Release files / pqapi-7.4.0-py3-none-any.whl

Download URL	pqapi-7.4.0-py3-none-any.whl
Size	14.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`87ad8c2864ecc33e8ff41e37ae39e200d1c341f4e8ac67a0251e136332e4980a`
BLAKE2b-256 checksum How to use checksums	`fbbcf771ce6906eacee3df367267ae2d44a3dc073f08175cfe39edfe563af85d`
Upload date	Jul 29, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.12.9`