# Read question research Source: https://docs.musicnerd.net/api-reference/research/question-status Read question research progress ## GET /api/artist/{id}/research/questions/{jobId} Full OpenAPI specification: https://docs.musicnerd.net/spec/question-research.json ## Authentication This operation requires one of the security alternatives in the specification below. Security scheme definitions are included where present in the published specification. [Authentication guide](https://docs.musicnerd.net/authentication) ## Operation and referenced schemas ```json { "openapi": "3.1.0", "info": { "title": "Question-directed artist research", "version": "0.1.0", "description": "Preview contract. Apply the Web-owned research schema before enabling the matching API implementation. Web Ask About reserves a bounded planning slot before its model call: at most 10 new question plans per artist and 200 globally over rolling 24 hours, recorded without question or conversation text. This is separate from the API research ledgers; polling existing jobs does not plan again. Rejected reservations perform no model call. Planning uses no automatic model retries." }, "servers": [ { "url": "https://musicnerd-api.vercel.app" } ], "paths": { "/api/artist/{id}/research/questions/{jobId}": { "get": { "summary": "Read question research progress", "description": "Safe resumable progress and bounded original references; no raw request, provider payload or private interview memory.", "security": [ { "PrivyAuth": [] }, { "ResearchService": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Current claimant/admin required for private operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unavailable artist, job or evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State or revision changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Evidence exceeds supported bounds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Research quota or active-work limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "For a quota response, matches retryAfterSeconds from its actual rolling-window boundary. Active-work conflicts retain a short retry hint.", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Storage, credential or provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Status": { "type": "object", "required": [ "status", "jobId", "stage", "message", "updatedAt", "references", "limitations" ], "properties": { "status": { "const": "ok" }, "jobId": { "type": "string", "format": "uuid" }, "stage": { "type": "string", "enum": [ "checking_saved", "searching", "reading", "transcribing", "waiting_provider", "complete", "unresolved", "failed", "cancelled" ] }, "message": { "type": "string" }, "provider": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string", "format": "date-time" }, "reused": { "type": "boolean" }, "references": { "type": "array", "maxItems": 6, "items": { "$ref": "#/components/schemas/Reference" } }, "limitations": { "type": "array", "items": { "type": "string" } }, "outsideResearchReason": { "type": "string", "enum": [ "quota" ], "description": "Outside collection was not admitted. Saved sources may still provide a bounded answer. New quota-blocked jobs include a shared quota scope and reset time; retry from a new question after reset, without restarting this terminal job. Older saved-only jobs can omit reset metadata." }, "selection": { "type": "string", "enum": [ "candidates", "research" ], "description": "Optional for legacy jobs. candidates is an unassessed evidence selection, not an answer or a sufficiency finding. If the checked answer is insufficient, continue this same job. research means the normal bounded research path." }, "quotaScope": { "type": "string", "enum": [ "saved_global", "outside_artist", "outside_global" ], "description": "Shared operational budget that blocked this work, never a personal visitor limit." }, "retryAfterSeconds": { "type": "integer", "minimum": 0, "description": "Seconds until resetAt, rounded up. A current status read recomputes this duration; new traffic can consume later capacity." }, "resetAt": { "type": "string", "format": "date-time", "description": "Actual rolling-window boundary calculated when the quota was checked." } } }, "Error": { "type": "object", "required": [ "status", "error", "code" ], "properties": { "status": { "const": "error" }, "error": { "type": "string" }, "code": { "type": "string" }, "quotaScope": { "type": "string", "enum": [ "saved_global", "outside_artist", "outside_global" ], "description": "Shared operational budget that blocked this work, never a personal visitor limit." }, "retryAfterSeconds": { "type": "integer", "minimum": 0, "description": "Seconds until resetAt, rounded up. A current status read recomputes this duration; new traffic can consume later capacity." }, "resetAt": { "type": "string", "format": "date-time", "description": "Actual rolling-window boundary calculated when the quota was checked." } } }, "Reference": { "type": "object", "required": [ "sourceId", "revision", "start", "end", "text", "url", "curation" ], "properties": { "sourceId": { "type": "string", "description": "Stable current source reference, including latest::<64hex> provider snapshot originals. Removing/changing the connected account or successfully refreshing away a hidden/removed item makes its old reference unavailable; changed originals have a different revision." }, "revision": { "type": "string" }, "start": { "type": "integer", "minimum": 0 }, "end": { "type": "integer", "minimum": 0 }, "text": { "type": "string" }, "url": { "type": "string" }, "curation": { "type": "string", "enum": [ "approved", "pending" ] }, "evidenceKind": { "type": "string", "enum": [ "original_text", "caption", "provider_transcript" ] }, "speaker": { "type": "string", "enum": [ "not_applicable", "unverified" ] }, "publishedAt": { "type": [ "string", "null" ] }, "retrievedAt": { "type": [ "string", "null" ] }, "truncated": { "type": [ "boolean", "null" ] }, "activityDate": { "type": "string", "description": "Optional provider activity date. Preserves YYYY, YYYY-MM or full date/time precision. Never substitutes for source publication time." }, "activityDateKind": { "type": "string", "enum": [ "release", "moment" ], "description": "Meaning of activityDate. Exact catalog release-date claims require original catalog text, not publishedAt." } } } }, "securitySchemes": { "PrivyAuth": { "type": "http", "scheme": "bearer", "description": "Current artist claimant or administrator Privy access token." }, "ResearchService": { "type": "apiKey", "in": "header", "name": "X-MusicNerd-Research-Key", "description": "Server-only MUSICNERD_RESEARCH_API_KEY. Public evidence research only; never grants review or interview-history access." } } } } ```