Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.clavata.ai/llms.txt

Use this file to discover all available pages before exploring further.

For technical docs see the Batch Processing API.

​
How it Works

Using the Batch API is a three-step process. You must follow these steps in order to successfully process your data.
  1. Create a Batch Job: First, you make an API request to create a new job. This initial call will return a job_id and a secure, pre-signed URL that you will use to upload your data.
  2. Upload Your Input File: Next, you will upload your data file to the pre-signed URL provided in Step 1. The file must be in the specified CSV format. See below for details. The job will automatically start processing shortly after the upload is complete.
  3. Check Job Status: To monitor the progress of your job, you will need to periodically poll the ‘Get Batch Job’ endpoint using your job_id.

​
Create a Batch Job

Creating a Batch Job is very simple. Sending in a request will grant you a URL to upload your content to. The URL is only good for 4-hours so be sure to upload your content before that expires. If you miss the window then you will need to create another job.

​
Upload Your Input File

Currently Moonbounce supports uploading your content via a CSV.
Each Batch Job can only take one file at a time. Uploading more than one CSV will overwrite the oldest.

​
Text

Text processing requires the below:
  • ref_id - this could be a numbered list, a content guid, or any other identifier so long as it is unique in the row.
  • type - this should be set to ‘text’
  • content - should contain the content you wish to have evaluated
ref_id, type, content
1, text, hello
2, text, nice to meet you
3, text, have a great day!
Download text example

​
Image

Image processing requires the below:
  • ref_id - this could be a numbered list, a content guid, or any other identifier so long as it is unique in the row.
  • type - this should be set to ‘image_url’
  • content - should contain the content you wish to have evaluated
ref_id, type, content
568695, image_url, https://image.com/1234_fuzzy_bunny.png
568696, image_url, https://image.com/5678_fluffy_cat.png
568727, image_url, https://image.com/0912_funny_dog.png
Download image example
Ensure your image URLs are publicly accessible!

​
Check Job Status

You will need to check on your job status periodically. When the job status returns BATCH_JOB_STATE_COMPLETED, the response from the API call will also contain a output_url to download your results. This URL is valid for 4-hours. Each pull of Batch Job Status will return a new URL for completed jobs. Each of these are good for 4-hours.
Batch job records and API responses are subject to job results retention (at least 30 days; archived jobs return 404; contact support to request recovery).

​
Stages

Your job will pass through several stages. You can monitor these by polling Get batch jobs.
  • BATCH_JOB_STATE_QUEUED - Your job is in the queue waiting for processing.
  • BATCH_JOB_STATE_PREPROCESSING - Your job is being prepared and validated.
  • BATCH_JOB_STATE_SUBMITTED - Your job has been submitted to the AI for evaluation.
  • BATCH_JOB_STATE_POSTPROCESSING - The results are being compiled.
  • BATCH_JOB_STATE_COMPLETED - Your job is complete and the results are ready to be downloaded.
  • BATCH_JOB_STATE_ERROR - Your job has encountered an error.

​
Output File

The results CSV contains the following columns:
ColumnDescription
ref_idThe reference ID you provided in the input file.
typeThe content type: text or image_url.
labelsA JSON array of all evaluated labels and their scores (see below). Empty if evaluation failed.
contentThe original content that was evaluated.
errorAn error message if the item failed processing. Empty on success.

​
Labels format

The labels column contains a JSON array of objects, each with a label name and a score between 0 and 1: 
[
  {"label": "Civil/Baseline", "score": 0.988},
  {"label": "Casual Dating", "score": 0.976},
  {"label": "Unstated/Exploring", "score": 0.964}
]
Every label defined in your policy is included with its score, regardless of whether it matched. Use the scores to determine which labels apply to each piece of content.

​
Performance Expectations

A job can take 24-48 hours to complete. Processing time is not guaranteed and can vary significantly based on several factors:
  • Job Size: Larger jobs will naturally take longer to complete.
  • Content Type: Image processing is more resource-intensive and will take longer than text processing.
  • Policy Complexity: Jobs run against policies with a higher number of assertions or more complex logic will require more processing time.
  • System Queue: There may be a delay before your job begins processing as it waits in our internal queue.