ChartQuery

Java

Install the ChartQuery Java SDK and make your first API call.

The official Java SDK for ChartQuery, with one typed method per endpoint and a generic request() for anything else.

Requirements

  • Java 17+

Install

The Java SDK is not on Maven Central. Build it from source to install it in your local Maven repository, then add it to your project.

git clone https://github.com/chartquery/chartquery-java.git
cd chartquery-java
mvn -q install -DskipTests
Maven
<dependency>
  <groupId>com.chartquery</groupId>
  <artifactId>chartquery</artifactId>
  <version>0.1.0</version>
</dependency>
Gradle
implementation("com.chartquery:chartquery:0.1.0")

Get your API key

Copy your API key from the ChartQuery dashboard and set it in the CHARTQUERY_API_KEY environment variable, which the SDK reads by default. Keep it out of source control.

Quick start

import com.chartquery.ApiResponse;
import com.chartquery.ChartQueryClient;
import com.chartquery.params.ChartAiParams;

ChartQueryClient client = ChartQueryClient.fromEnv();
ApiResponse response = client.chartAi(ChartAiParams.builder().prompt("Monthly revenue 2026 as a bar chart: Jan 10, Feb 14, Mar 18").build());
System.out.println(response.json().toPrettyString());

Async jobs

Any call accepts is_async, which is useful past the 60-second server limit. The response is then a job_id, and the SDK can wait for the job to finish.

ApiResponse submitted = client.chartAi(ChartAiParams.builder().prompt("Monthly revenue 2026 as a bar chart: Jan 10, Feb 14, Mar 18").isAsync(true).build());
ApiResponse job = client.waitForJob(
    submitted.json().get("job_id").asText(),
    Duration.ofSeconds(3),
    Duration.ofHours(12),
    progress -> System.out.println(progress.path("status").asText() + " " + progress.path("progress").asInt()));

Errors

A non-2xx response raises an API error with its status and message. See Status codes for the full list.

try {
  client.chartAi(ChartAiParams.builder().prompt("Monthly revenue 2026 as a bar chart: Jan 10, Feb 14, Mar 18").build());
} catch (ChartQueryApiException e) {
  System.err.println(e.status() + ": " + e.getMessage());
}

Retries

Requests are retried up to 3 times after a network error, a 408, 500, 502, 503 or 504, or a plan rate limit. Per-key quota errors and client-side timeouts are not retried. The delay starts at 1 second and grows 1.5× per retry, and a Retry-After header wins.

ChartQueryClient client = ChartQueryClient.builder().maxRetries(5).retryDelay(Duration.ofMillis(500)).build();
client.chartAi(ChartAiParams.builder().prompt("Monthly revenue 2026 as a bar chart: Jan 10, Feb 14, Mar 18").build(), RequestOptions.builder().maxRetries(0).build()); // one request without retries

Batch requests

Run many calls at once, 10 at a time by default. One failure does not stop the others.

List<String> inputs = List.of("Monthly revenue 2026 as a bar chart: Jan 10, Feb 14, Mar 18", "Market share as a pie chart: A 40, B 35, C 25");
List<BatchResult<ApiResponse>> results = client.batch(inputs, 5, value ->
    client.chartAi(ChartAiParams.builder().prompt(value).build()));
for (BatchResult<ApiResponse> result : results) {
  if (result.ok()) {
    System.out.println(result.value().json());
  } else {
    System.err.println(inputs.get(result.index()) + ": " + result.error().getMessage());
  }
}

Any endpoint

request() reaches any path, including endpoints released after your SDK version.

ApiResponse response = client.request("GET", "/v1/usage", Map.of());

Common mistakes

  • Putting the API key in front-end code. Anyone could read it. Call the API from your server.
  • Treating every 401 as a bad key. A 401 can also be a rate limit: read the message. The SDK retries plan rate limits for you.
  • Retrying a 402. It means there are no credits or quota left, so a retry cannot succeed. See Credits.
  • Waiting on long requests. Past 60 seconds, use async mode as shown above rather than raising your timeout. See Timeout.

On this page