Skip to main content
GET
https://app.firmware.ai
/
api
/
v1
/
research
List deep research
curl --request GET \
  --url https://app.firmware.ai/api/v1/research \
  --header 'Authorization: Bearer <token>'
{
  "docs": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "succeeded",
      "title": "Latest Advancements in Quantum Computing",
      "topic": "What are the latest advancements in quantum computing?",
      "createdAt": "2026-01-20T14:30:00.000Z",
      "updatedAt": "2026-01-20T14:35:00.000Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "status": "running",
      "title": "Researching...",
      "topic": "Compare React vs Vue for enterprise applications",
      "createdAt": "2026-01-20T14:25:00.000Z",
      "updatedAt": "2026-01-20T14:25:00.000Z"
    }
  ],
  "totalDocs": 2
}
Retrieve a list of all your deep research jobs. Filter by status, date, or topic to find what you need.

​
Authenticate

Use an API key in the Authorization header. 
curl https://app.firmware.ai/api/v1/research \
  -H "Authorization: Bearer $FIRMWARE_API_KEY"

​
Query parameters

​
limit
integer
default:"20"
Maximum number of results to return. Max 100.
​
sort
string
default:"-createdAt"
Field to sort by. Prefix with - for descending order.Examples: -createdAt, title, -updatedAt
​
where
string
JSON-encoded filter query using Payload’s query syntax.Supports operators: equals, not_equals, contains, exists, greater_than, less_than, in, not_in, and more.Use and / or for complex queries.
{
  "metadata.research.status": {
    "equals": "succeeded"
  }
}

​
Response

​
docs
array
Array of research job summaries.
​
totalDocs
integer
Total number of research jobs matching the query.

​
Examples

curl "https://app.firmware.ai/api/v1/research" \
  -H "Authorization: Bearer $FIRMWARE_API_KEY"

{
  "docs": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "succeeded",
      "title": "Latest Advancements in Quantum Computing",
      "topic": "What are the latest advancements in quantum computing?",
      "createdAt": "2026-01-20T14:30:00.000Z",
      "updatedAt": "2026-01-20T14:35:00.000Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "status": "running",
      "title": "Researching...",
      "topic": "Compare React vs Vue for enterprise applications",
      "createdAt": "2026-01-20T14:25:00.000Z",
      "updatedAt": "2026-01-20T14:25:00.000Z"
    }
  ],
  "totalDocs": 2
}

​
Where query examples

​
Filter by status

{
  "status": {
    "equals": "succeeded"
  }
}

​
Filter by date range

{
  "createdAt": {
    "greater_than": "2026-01-01T00:00:00.000Z"
  }
}

​
Complex query with AND/OR

{
  "or": [
    {
      "status": {
        "equals": "succeeded"
      }
    },
    {
      "status": {
        "equals": "running"
      }
    }
  ]
}

​
Search by topic

{
  "topic": {
    "contains": "quantum"
  }
}