cURL
curl --request GET \
--url https://api.timbal.ai/orgs/{org_id}/k2/{kb_id}/files/{file_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.timbal.ai/orgs/{org_id}/k2/{kb_id}/files/{file_id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.timbal.ai/orgs/{org_id}/k2/{kb_id}/files/{file_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.timbal.ai/orgs/{org_id}/k2/{kb_id}/files/{file_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.timbal.ai/orgs/{org_id}/k2/{kb_id}/files/{file_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.timbal.ai/orgs/{org_id}/k2/{kb_id}/files/{file_id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.timbal.ai/orgs/{org_id}/k2/{kb_id}/files/{file_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"content_length": 123,
"content_type": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"id": 123,
"kb_id": 123,
"metadata": "<unknown>",
"name": "<string>",
"parse_state": "<string>",
"uid": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"url": "<string>",
"embeddings": [
{
"created_at": "2023-11-07T05:31:56Z",
"id": 123,
"kb_file_id": 123,
"model": "<string>",
"provider": "<string>",
"status": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"chunk_count": 123,
"cost_usd": 123,
"error": "<string>",
"parsing_id": 123,
"token_count": 123
}
],
"parsings": [
{
"created_at": "2023-11-07T05:31:56Z",
"id": 123,
"kb_file_id": 123,
"provider": "<string>",
"status": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"chunk_count": 123,
"cost_usd": 123,
"error": "<string>",
"num_pages": 123,
"provider_job_id": "<string>",
"s3_bucket": "<string>",
"s3_key": "<string>"
}
],
"directory": "<string>",
"signed_url": "<string>"
}Files
Get File
Get a file with its parsings and embeddings metadata
GET
/
orgs
/
{org_id}
/
k2
/
{kb_id}
/
files
/
{file_id}
cURL
curl --request GET \
--url https://api.timbal.ai/orgs/{org_id}/k2/{kb_id}/files/{file_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.timbal.ai/orgs/{org_id}/k2/{kb_id}/files/{file_id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.timbal.ai/orgs/{org_id}/k2/{kb_id}/files/{file_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.timbal.ai/orgs/{org_id}/k2/{kb_id}/files/{file_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.timbal.ai/orgs/{org_id}/k2/{kb_id}/files/{file_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.timbal.ai/orgs/{org_id}/k2/{kb_id}/files/{file_id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.timbal.ai/orgs/{org_id}/k2/{kb_id}/files/{file_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"content_length": 123,
"content_type": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"id": 123,
"kb_id": 123,
"metadata": "<unknown>",
"name": "<string>",
"parse_state": "<string>",
"uid": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"url": "<string>",
"embeddings": [
{
"created_at": "2023-11-07T05:31:56Z",
"id": 123,
"kb_file_id": 123,
"model": "<string>",
"provider": "<string>",
"status": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"chunk_count": 123,
"cost_usd": 123,
"error": "<string>",
"parsing_id": 123,
"token_count": 123
}
],
"parsings": [
{
"created_at": "2023-11-07T05:31:56Z",
"id": 123,
"kb_file_id": 123,
"provider": "<string>",
"status": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"chunk_count": 123,
"cost_usd": 123,
"error": "<string>",
"num_pages": 123,
"provider_job_id": "<string>",
"s3_bucket": "<string>",
"s3_key": "<string>"
}
],
"directory": "<string>",
"signed_url": "<string>"
}Listings from
GET /orgs/{org_id}/k2/{kb_id}/files include folder rows (content_type application/vnd.timbal.k2-directory). This get file endpoint is only for regular uploaded files (parsings, embeddings, etc.).
If you pass a directory row’s id from the list endpoint, the API responds with 404 Not Found — virtual directories do not have a full file payload here.Authorizations
Timbal API key. Obtain your API key from the Timbal platform settings. See Authentication for more information.
Response
200 - application/json
File details with parsings and embeddings
Pipeline state for parsing + embedding.
One of pending (pipeline in flight), success (parse + embed both completed),
failed (latest attempt failed), or skipped (format unsupported, never parsed).
Unsupported files are stored as-is; the indicator lets clients flag them in listings
rather than rejecting the upload.
Deprecated: prefer signed_url when present. Kept for old clients.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
CloudFront signed URL on the new CDN for private content. Omitted when signing is unavailable or the object is public.